Microsolt BASIC 


Professional Development System 


Guide to Keystrokes 


The following table lists the most commonly used keystrokes in the QuickBASIC Extended 
(QBX), Programmer's WorkBench (PWB), and CodeView environments. Unless stated 
otherwise, each keystroke has the same function in all three environments. 


Alt 


Ese 


Fl 


Shift + Fl 


F4 


F5 

F6 

Shift + Arrow 
Ctrl + Ins 

Shift + Del 

Shift + Ins 

Alt + Backspace 
Ctrl + Backspace 


Activate the menu bar. Press the highlighted characters in the menu 
names to open menus and to choose commands from a menu. Or, use the 
Left Arrow and Right Arrow keys to highlight a menu title, and then 
press the Up Arrow and Down Arrow keys to choose a command. 
Pressing Alt a second time closes all open menus and deactivates the 
menu bar. 


Exit Help. Esc also closes menus and dialog boxes, cancelling any 
entries. 


Invoke the online Help system. To get help, move the cursor to the topic 
on which you want more information: a keyword, a command, a dialog 
box, or an error message. Then press F1. To exit Help press Esc. 


In the QBX environment, Shift + Fl explains Help. In PWB and 
Code View, Shift + Fl displays the Help Contents. 


Display the output screen from within the environment. Pressing F4 a 
second time returns you to the environment. 


Begin executing the currently loaded program. 

Move the cursor between visible windows. 

Select text. 

Copy selected text. 

Cut selected text. 

Paste cut or copied text at the current cursor position. 
Undo the previous edit. 


Restore the edit you've undone. 
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Introduction 


Welcome to Microsoft® BASIC version 7.1 Professional Development System. Microsoft 
BASIC includes the tools and files you'll need to create and debug large, sophisticated BASIC 
programs that run under the DOS and OS/2 operating systems. The Microsoft BASIC package 
includes the following: 


a Microsoft QuickKBASIC Extended (QBX) development environment 
s Microsoft Programmer's WorkBench (PWB) development environment 
s BASIC compiler (BC) 
a Integrated Indexed Sequential Access Method (ISAM) package 
a Major utilities: 
= Microsoft Segmented-Executable Linker (LINK) 
= Microsoft Library Manager (LIB) 
= Microsoft Program-Maintenance Utility (NMAKE) 
= Run-Time Module Build Utility (BUILDRTM) 
= Microsoft Help File Creation Utility (HELPMAKE) 
= Microsoft QuickHelp 
w Add-on libraries: Date/Time, Financial, and Format 
= Toolboxes: Matrix Math, Presentation Graphics, and User Interface 
=» Microsoft CodeView« debugger and other mixed-language development tools 


ws Printed and online documentation 


Distribution of Run-Time Modules 


As described in Paragraph 5 of the Microsoft License Agreement included with this product. 
the following run-time modules may be distributed under the terms and conditions listed in the 
agreement: 

BRT71xxx.EXE, BRT71xxx.DLL, HELVB.FON, TMSRB.FON, MSHERC.COM. 


MOUSE.COM, PATCH87.EXE, FIXSHIFT.COM, PROISAM.EXE, PROISAMD.ENE. 
ISAMIO.EXE, ISAMCVT.EXE, ISAMPACK.EXE, and ISAMREPR.EXE. 


These modules can only be distributed in conjunction with and as a necessary and integrated 
component of your software product, in such a manner that they enhance or supplement the 
core value otherwise existing in your software product. 
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The following copyright notice applies to this product for purposes of run-time module 
distribution: 


Portions(C) 1982-1990 Microsoft Corporation. All rights reserved. 


Documentation 


vi 


Microsoft BASIC 7.1 includes a full set of printed and online documentation. 


Printed Documentation 


Getting Started gets you up and running with Microsoft BASIC. 


The Programmer's Guide provides information about programming concepts and techniques. 
The first part of the manual focuses on the features of the BASIC language, including such 
topics as control-flow structures, string processing, and error/event handling. The second part 
ot the manual describes program development utilities supplied with Microsoft BASIC. These 
chapters give the syntax and command-line options for each utility, as well as illustrative 
examples. The appendixes contain the BASIC language definitions. 


The BASIC Language Reference is divided into three parts. Each part begins with summary 
tables listing the functions and statements described in that part, followed by individual 
reference descriptions in alphabetical order. 


e Part 1, “Language Reference,” describes Microsoft BASIC functions, statements, and 
metacommands. 


ew Part 2, “Add-On-Library Reference,” describes the functions in the add-on libraries. 
ea Part 3. “BASIC Toolbox Reference,” describes the procedures in the BASIC toolboxes. 


The appendixes describe keyboard/scan codes, reserved words, command-line tools, and error 
messages, 


Online Documentation 


Microsoft BASIC puts a complete online reference database at your fingertips with the new 
Microsoft Advisor online Help system. Online Help gives you context-sensitive Help for the 
BASIC language, QBX, command-line compiler options, error messages, and symbols in your 
programs. See Chapter 6, “Using Online Help,” for more information. 
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Document Conventions 


Microsoft documentation uses the term “OS/2” to refer to the OS/2 systems—Microsoft 
Operating System/2 (MS® OS/2) and IBM OS/2. Similarly, the term “DOS” refers to the 
MS-DOS® and IBM Personal Computer DOS operating systems. The name of a specific 
operating system is used when it is necessary to note features that are unique to that system. 


This manual uses the following typographic conventions: 


Example of convention 


BASIC.LIB, ADD.EXE, COPY, LINK 


SUB, IF, LOOP, PRINT, TIME$ 


Bad File Mode 


handles 


[|disksize]] 


{ WHILE! UNTIL} 


Ctrl key 


Alt+F 1 


Down Arrow key 


Description 
Words you type appear in this boldface font. 


Uppercase (capital) letters indicate filenames 
and operating-system environment variables 
and commands. 


Bold uppercase letters indicate language- 
specific keywords with special meaning to 
Microsoft BASIC or another Microsoft 
language. 


This font is used for error messages. 


Italic letters indicate placeholders for 
information you supply. Italics are also 
occasionally used in the text for emphasis. 


Items inside double square brackets are 
optional. 


Braces and a vertical bar indicate a mandatory 
choice between two or more items. You must 
choose one of the items unless all of the items 
also are enclosed in double square brackets. 


Initial capital letters are used tor the names of 
keys and key sequences, such as Enter and 
Ctrl+R. The key names used in this manual 
correspond to the names on the IBM Personal 
Computer keyboard, Other machines may use 
different names. 


A plus (+) indicates a combination of keys. For 


example, Alt+F] means to hold down the Alt 
key while pressing the Fl key. 


The cursor movement (“arrow”) keys are called 


direction keys. Individual direction keys are 


referred to by the direction of the arrow on the 


key top (Left, Right, Up, or Down). 
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vill 


“detined term” 


Video Graphies Array (VGA) 
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Quotation marks usually indicate a new term 
detined in the text. 


Acronyms are usually spelled out the first time 
they are used. 


Chapter 1 
New Features 


Microsoft BASIC combines powerful new language features with capacity, performance. and 
usability enhancements to provide a high-productivity development system for professional 
BASIC programmers. This chapter describes the new features for versions 7.0 and 7.1. Changes 
for version 7.1 are indicated by the words “Version 7.1” in the left margin. 


New Features in Version 7.1 


Microsoft BASIC version 7.1 extends BASIC’s power under OS/2. improves its compatibility 
with other languages, and provides new language features: 


BASIC’s Indexed Sequential Access Method (ISAM) is now fully supported for OS/2. 


The Programmer’s WorkBench (PWB) provides a sophisticated development environment 
for mixed-language programming under DOS or OS/2. 


The CodeView debugger version 3.0 contains many improvements to simplify the task of 
debugging large BASIC and mixed-language programs under DOS or OS/2. 


QuickHelp provides access to the Microsoft Advisor Help system from the command line. 


The new REDIM PRESERVE statement lets you change the size of an array without 
erasing the data it contains. 


BASIC now supports passing parameters by value within BASIC procedures and passing 
arrays containing fixed length strings as parameters. 


BASIC is fully compatible with Microsoft C version 6.0. 


The rest of this chapter discusses the features new to Microsoft BASIC versions 7.0 and 7.1 in 
greater detail. 


Language Enhancements 


Microsoft BASIC contains major language enhancements designed for business. scientific, and 
general-purpose BASIC programming. 
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Integrated ISAM 


The Indexed Sequential Access Method package provides a fast and simple method for 
accessing specific records in large and complex data files. Microsoft BASIC integrates all 
ISAM statements and functions with the BASIC language. BASIC ISAM includes statements 
for transaction processing and for data retrieval and manipulation. 


In version 7.1, ISAM statements and functions are supported for OS/2 as well as DOS. 
Microsoft BASIC also includes several utilities for use with ISAM files created with BASIC: 
ses ISAMCVT.EXE (DOS only) converts Btrieve and dBASE files for use with ISAM. 

ae ISAMREPR.EXE repairs corrupted ISAM databases. 

ge ISAMPACK.EXE compacts ISAM files to save disk space. 

e ISAMIO.EXE converts ASCII files to ISAM format and vice versa. 


For more information about ISAM, see Chapter 10, “Database Programming with ISAM.” in 
the Programmer's Guide. 


DOS File Management 


The DIR$ and CURDIR$ functions and the CHDRIVE statement make it easier to manage 
DOS files from BASIC programs. 


DIR$ is similar to the DOS DIR command, except that the filenames are returned one at 
atime. CURDIR$ returns the current directory specification, and CHDRIVE changes the 
current drive. 


Currency Data Type 


The currency data type maintains to-the-penny precision while providing the speed of integer 
math for programming accounting tasks. Its internal representation as an integer gives this type 
a significant advantage in speed over the floating-point data type for operations such as addition 
and subtraction. For more information about the currency data type, see Chapter 15, 
“Optimizing Program Size and Speed,” in the Programmer's Guide. 


Procedure-Level Error Handling 


Microsoft BASIC contains local error trapping and handling for procedures, making error 
handling much more efficient. In previous versions of BASIC, error-handling routines existed 
at the module level. When a handler was turned on, it was active for all procedures within the 
module. 
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New Features 


With Microsoft BASIC, you can create both module-level and procedure-level error handlers. 
The same error can invoke different error-handling routines, depending on which procedure is 
running. For example, you may want to invoke different error-handling routines for ERR code 
54, Bad File Mode, because the error has different meanings for different file operations. For 
more information on error handling, see Chapter 8, “Error Handling,” in the Programmer’ s 
Guide. 


Static Arrays in Records 


In previous versions of BASIC, you could create user-defined data structures that contained 
numeric and fixed-string data types by using the TYPE...END TYPE statements. Now you can 
use static arrays in addition to numeric and string data types. which gives you more flexibility 
in building data structures. 


Preserve Data when Redimensioning an Array 


By adding the PRESERVE option to the REDIM statement, you can preserve the data that 
exists in an array when changing its outer boundary. This simplifies the dynamic control of the 
amount of memory consumed by an array. For details and an example, see the online Help on 
the REDIM statement . 


Improved Parameter Passing 


With previous versions of BASIC, you could emulate passing parameters by value by 
surrounding the parameter with parentheses. Now you can use the BYVAL keyword in 
DECLARE, SUB, and FUNCTION statements for BASIC procedures. For details on passing 
parameters by value, see the online Help for the DECLARE, SUB, and FUNCTION 
statements. 


BASIC now also supports passing arrays containing fixed-length strings as parameters. For 
more information, see the online Help for the SUB and FUNCTION statements. 


Improved COM Support with ERDEV$ and ERDEV 


With previous versions of BASIC, if you had a device timeout error, there was no way to tind 
out which device timed out, or which control line caused the timeout. With Microsoft BASIC. 
information about the timeout is available through the ERDEV$ and ERDEY functions. 
ERDEV$ indicates whether a timeout is occurring on the communications port. ERDEV 
indicates the type of timeout error that occurred (that is, CTS, DSR, or DCD control-line 
errors). See the OPEN COM statement in the BASIC Language Reference for more 
information. 
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Date/Time, Financial, and Format Add-On Libraries 


With these new libraries, you can use BASIC to perform spreadsheet-style calculations and 
formatting. For example, you can compute the number of days between two dates by converting 
the dates from month-day-year format to number format, and then subtracting. You can use 
financial functions to calculate double-declining balance depreciation, future value, net present 
value, internal rate of return, and other common financial calculations. For more information 
about Date/Time, Financial, and Format add-on libraries, see Part 2 of the BAS/C Language 
Reference. 


Matrix Math Toolbox 


The new Matrix Math toolbox contains sample BASIC code for several common matrix math 
operations, including addition, subtraction, multiplication and division, matrix inversion, 
determinant calculation, and solution of simultaneous equations using Gaussian elimination. 
For more information about the Matrix Math toolbox, see Part 3 of the BAS/C Language 
Reference. 


Presentation Graphics Toolbox 


You can use the Presentation Graphics toolbox to display charts and graphs from your 
programs. The Presentation Graphics toolbox includes procedures for pie charts, bar and 
column charts, line graphs, and scatter diagrams. Figure 1.1 shows an example of a column 
chart created with this toolbox. 
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Figure 1.1 Presentation Graphics 
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The toolbox also includes a set of special graphics fonts. For more information about 
Presentation Graphics, see Chapter 6, “Presentation Graphics,” in the Programmer's Guide. 


User Interface Toolbox 


With the new user interface code samples, you can design your own user interface using 
BASIC procedures. The code samples in this toolbox give you complete control of character- 
based window interfaces. For example, you could write a BASIC program with multiple 
windows, menu bars, dialog boxes, and mouse interaction. For more information about the User 
Interface toolbox, see Part 3 of the BAS/C Language Reference. 


C Version 6.0 Compatibility 


Version 7.1 BASIC incorporates the C version 6.0 startup code. This makes BASIC fully compatible with 
the latest version of C. However, this can cause problems for mixed-language programmers 
who have earlier versions of C, FORTRAN, or Pascal. Compatible run-times for these 
languages are available free from Microsoft. Contact Product Support Services for more 
information. 


Capacity and Performance Enhancements 


Microsoft BASIC eliminates many of the capacity and performance barriers that former!) 
limited the size and sophistication of BASIC applications. 


Far String Support 


In previous versions of BASIC, all variable-length string data was stored in near memory. This 
relatively small portion of memory (64K maximum) also stores the rest of the simple 
variables—integers, floating-point numbers and fixed strings, all constants, the stack, and some 
run-time overhead. Even when the only variables you use are variable-length strings. your 
maximum data storage is limited. 


Microsoft BASIC supports “far strings.” which enable you to store variable-length string data 
outside of near memory in multiple segments of far memory. This gives you a full 64K of string 
storage in the module level of the main module, plus several additional 64K blocks of storage. 
depending on how you write your program. Removing variable-length strings from near 
memory creates significantly more room for other simple variables. For more information on 
using far strings, see Chapter 11, “Advanced String Storage,” and Chapter 13, “Mixed- 
Language Programming with Far Strings,” in the Programmer's Guide. 
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Overlay Support 


With overlays, you can write and run programs up to almost 16 megabytes in size when 
compiling and linking from the command line. In an overlaid version of a program, specified 
parts of the program are only loaded if and when they are needed. Specifying overlays can be 
usetul if you have compiled a program that is too large to load in memory. For more 
information about overlays, see Chapter 18, “Using LINK and LIB,” in the Programmer’ s 
Guide. 


Improved Granularity 


The extent to which BASIC run-time routines are divided into individually accessible pieces is 
called “granularity.” With Microsoft BASIC’s improved granularity, you can link with the 
minimum amount of library code needed to produce stand-alone programs. This gives you 
smaller compiled programs, saving disk space and memory. For more information, see 
Chapter 15, “Optimizing Program Size and Speed.” in the Programmer's Guide. 


Optimized Code Generation 


Optimized code generation automatically makes compiled BASIC programs smaller and faster. 
Also, using a new compiler switch, you can tell the compiler to generate code for the 80286 
(and later) microprocessor family, taking advantage of that family’s machine instructions. For 
more information on optimized code generation, see Chapter 15, “Optimizing Program Size and 
Speed.” in the Programmer's Guide. 


Improved Alternate Math Package 


For target systems without an 80x87 math coprocessor, the alternate math package gives 
programs greatly improved speed. For example, if your application involves spreadsheet-style 
math without recursive calculations, using the alternate math package may give you a 
noticeable performance increase. For more information about the alternate math package, see 
Chapter 15, “Optimizing Program Size and Speed,” in the Programmer's Guide. 


Improved IEEE Math Coprocessor Emulation 


For target systems with or without a math coprocessor, an improved coprocessor emulator gives 
you faster high-precision calculations, 


Improved Code Generation 


Relative jumps and short jumps to near targets are optimized, resulting in smaller, faster 
programs. This improvement affects all control statements. 
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Environment and Usability Enhancements 


Microsoft BASIC offers two sophisticated development environments: Microsoft QuickBASIC 
Extended (QBX) and Microsoft Programmer’s WorkBench (PWB). Both provide the following 
advanced features: 


a Integrated debugging capabilities within the environment and compatibility with Code View 
version 3.0 for debugging and optimizing executable programs at a variety of levels 


a Support for expanded memory specification (EMS 4.0) to create large executable programs 
a Undo/Redo capabilities 

= Customizable menus and key assignments 

a Control of build options and target environment from the development environment 

= Acomprehensive online Help system designed tor professional programmers 


In addition to QBX and PWB, BASIC now includes the QuickHelp environment for viewing 
Microsoft Advisor online Help files. 


The QuickBASIC Extended Environment 


Microsoft QuickBASIC Extended (QBX) is an advanced development environment for 
programmers who write most or all of their code in BASIC. It provides line-by-line syntax 
checking and on-demand program execution without recompiling. QBX also provides the 
following key features: 


es QBX automatically uses expanded memory. if present, for any parts of your program 
source code that are less than 16K in size. The View SUBs command now enables you to 
determine whether a program unit (module-level code or procedure) will fit into expanded 
memory. 


a Historical Undo/Redo commands. You can use Undo to step back through your last 20 
edits. 


es Acustomizable Utility menu. You can use the Utility menu to run DOS command-line 
programs or a custom editor, or for command-line compiling and overlay linking. You can 
even assign each menu item a shortcut key. 


e Customizable key assignments. If you prefer to use a set of editing commands other than 
the QBX detaults, you can change your key file to one of those provided. or you can create 
your own custom assignments. 


se Print to multiple printers or to a file. 
ws Debug watch window capacity doubled (from 8 to 16 expressions). 


es Complete control of compiler switches for compiling trom the environment. 


For information on using QBX, see Chapter 3,.°Using QuickKBASIC Extended.” 
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The Programmer’s WorkBench Environment 


Version 7.1 Microsoft Programmer's WorkBench (PWB) is an advanced development environment for 
programmers who often work in languages other than BASIC or who want to create, build, and 
debug their programs under OS/2. PWB also offers the following key features: 


PWB runs in real or protected modes, so you can write BASIC programs under DOS or 
OS$/2: 

You can write programs in any Microsoft professional-level language and mix languages, 
such as BASIC and C, within the environment. 


The Source Browser allows you to search selected files, list references and definitions, 
build a call tree and outline, and view a list of relationships among program symbols. 


You can step through compiler errors and PWB will indicate where each error occurred in 
the source code. 


PWB and Code View are integrated, so you can switch from one to the other without exiting 
PWB. 


Comprehensive Help is available on all command-line utilities and Microsoft languages 
installed on your system. 


For information on using PWB, see Chapter 4, “Using the Programmer's WorkBench.” See the 
PWB online Help for detailed information on performing tasks and customizing the 
environment. 


The CodeView Debugger 


The Code View debugger allows you to debug programs under DOS or OS/2. This is especially 
useful when you are using assembly language routines in a BASIC program. Code View version 
3.0 offers the following new features: 


Comprehensive online Help on how to use Code View. Help is also available on any 
installed Microsoft language or utility from within Code View. 


Automatic use of extended and expanded memory, if available. 


Full integration with PWB and compatibility with programs created in QBX. 


For introductory information on how to debug programs using this environment, see Chapter 5, 
“Using The Code View Debugger.” For detailed information on how to perform tasks in 

Code View and for information on how Code View evaluates BASIC expressions, see the 

Code View online Help. 


QuickHelp 


Microsoft QuickHelp reads Microsoft Advisor online Help files under DOS or OS/2. This 
provides you with an easy way to get Help on the command-line utilities and development 
environments without loading QBX, PWB, or Code View. 
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If you are using OS/2 or Microsoft Windows", you can run QuickHelp in one window and do 
your programming in another. This can be more convenient than using Help in the 
programming environment, which obscures part of the program you are working on. 


For more information on using QuickHelp, see Chapter 6, “Using Help.” 
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System Requirements 


Microsoft BASIC requires the following minimum configuration: 


= AnIBM Personal Computer XT or compatible running DOS version 3.0 or later. or OS/2 
version 1.1 or later. 


a A hard disk drive. 


mw A1.2M 5.25-inch floppy disk drive. (360K and 720K disk versions of this product are 
available from Microsoft. Contact Product Support Services for more information. ) 


mw 640K of available memory. 


Microsoft BASIC supports the Microsoft Mouse and any other pointing devices fully 
compatible with the Microsoft Mouse. 


Setup Overview 


Your Microsoft BASIC package includes the SETUP.EXE file on Disk | (Setup). You can use 
Setup in one of two ways: 


ws Install all the files you need to run BASIC, including the QBX environment. mixed- 
language development tools, utilities, and libraries. 


m Selectively install files. Typically, these might include libraries or tools you did not choose 
to install the first time you used Setup. 


Setup offers you a series of choices, letting you specify where to install the files and what 
features and utilities you want to install. To conserve disk space, you may choose not to use all 
of BASIC’s features at first. You can later run Setup to selectively install features you decide to 
add. 


Important You must run Setup to use Microsoft BASIC successfully. Setup decompresses files on the 
distribution disks (using UNPACK.EXE), builds libraries, and performs other operations to 
give you a usable BASIC environment. You cannot run BASIC by merely copying files from 
the distribution disks. 
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Setup contains information and Help screens to guide you through the setup process. The Setup 
Main menu points you to the various Setup screens where you can: 


e Specify paths and directories for installed files. 
a Specify libraries and run-time modules. 
mw Specify ISAM support. 


mw Specify files to install (for selective installation of specific files or parts of Microsoft 
BASIC). 


To run Setup, place Disk | (Setup) in disk drive A:, type a: setup at the system prompt. and 
then follow the instructions on your screen. Before running Setup, however. you should keep 
the following points in mind. 


Time Required to Install 


Set aside an uninterrupted block of time. You can exit Setup if you need to, but it will not retain 
any of the options you selected. Installing Microsoft BASIC requires anywhere from 30 
minutes to three hours, depending on the speed of your processor, available disk space. and the 
options you chose. For best performance, you should remove any terminate-and-stay-resident 
(TSR) programs from memory betore running Setup. 


Setup requires less time if you start it with the /BATCH option, as follows: 


It you use /BATCH, Setup will operate the same way that it does without the option, with one 
exception. Instead of building BASIC run-times and libraries automatically, SETUP /BATCH 
creates a batch file named BUILD.BAT. You must run this batch file from the command line to 
complete the installation process. 


Amount of Disk Space Required 


The amount of disk space required varies depending on which features you choose to install. 
However, Setup determines the exact amount of space you need before proceeding with 
installation. It then checks available disk space. If you lack sufficient space, Setup prompts you 
to change the number of files to install. If you do not have sufficient disk space and you choose 
to continue, the installation may not be successtul. 


Custom or Default Configuration 


The first time you install BASIC, you may not be sure which features you want to use. If this ts 
the case, you may want to install with the default settings. You can always change these 
settings by running Setup again. To install the default configuration, choose Install with Current 
Options from the Setup Main menu, as shown in Figure 2.1, and then follow the instructions on 
your screen. 
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Figure 2.1 Install with Current Options 


Setup Will Not Install Until You Tell It To 


If you want to install only a few files or you want to change the configuration. you can browse 
through the various Setup screens and alter settings. You can spend as much time as you want: 
Setup takes no action until you choose Install with Current Options from the Setup Main menu. 


Files Installed 


During installation, Setup places a number of .EXE, .LIB and .OBJ files in the directories you 
specify, as well as documentation and sample-code files. Note that Setup may replace existing 
files. Therefore, it is a good idea to have Setup install files only to new directories. empty 
directories, or directories containing software you want to update. 


Some of the .OBJ files are stub files. Depending on how you want to use BASIC. you might 
want to delete these files after installation. Before doing so, however, you should read the 
section “How Setup Uses Stub Files” later in this chapter. 


After Running Setup 


After you install Microsoft BASIC, you may want to do the following tasks: 
w Create or modify the TOOLS.INI file 
s Modify your environment variables 


a Unpack individual files from the distribution disks 


Creating or Modifying TOOLS.INI 


Programmer’s WorkBench, Code View, QuickHelp, and NMAKE, all included with Microsoft 
BASIC, use the TOOLS.INI file for initialization information. Setup installs a file named 
TOOLS.PRE that contains preliminary settings for these applications. Setup places 
TOOLS.PRE in the \BC7\BINB directory by default. 


If you don't have an existing TOOLS.INI file. you can rename TOOLS.PRE and place it ina 
directory that is indicated by your INIT environment variable. 


If you already have a TOOLS.INI file and you have not previously installed any of these 
applications, you can append TOOLS.PRE to your existing TOOLS.INI file. For example: 


“:\INIT>COPY TOOLS.INI + \BC7\BINB\TOOLS.PRE 
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If you have previously installed one or more of the applications mentioned above, you may 
want to selectively combine your existing TOOLS.INI settings with the additional settings in 
TOOLS: PRE, 

The TOOLS.PRE file contains information about modifying the initial settings for each of the 
applications. Online Help is also available from within PWB, Code View, and QuickHelp on the 
TOOLS.INI topic. 


Modifying Your Environment Variables 


Setup creates two files that you can use to change your environment variables: 
NEW-VARS.BAT for DOS, and NEW-VARS.CMD for OS/2. You can run these files from the 
command line, or you can append them to your AUTOEXEC.BAT file (DOS) or your 
COMNFIG.SYS file (OS/2). 

If you are installing for OS/2, you should also modify the LIBPATH line in your CONFIG.SYS 
file to include the directory where Setup installed BASIC’s dynamic-link libraries (DLLs). By 
default, Setup places these files in the \BC7\BINP directory. Since LIBPATH is not part of the 
environment, NEW-VARS.CMD cannot modify it. If you change LIBPATH, you will have to 
restart your system in order for it to take effect. 


Unpacking Individual Files 


The files provided on the Microsoft BASIC distribution disks are compressed to conserve 
space. A dollar sign ($) is added to the file extension to show that these files must be unpacked 
before they can be used. The file PACKING.LST contains a table showing how the modified 
file extensions correspond to the unpacked files. 


Setup automatically unpacks and installs all of the files you need to use the configuration you 
specified from the Setup menus. You can unpack individual files after Setup in order to modify 
your installation without rerunning Setup, to restore a file that was deleted, or to provide special 
support for mixed-language programming with Microsoft C version 6.0. 


To unpack a file from a distribution disk, use the following syntax: 

UNPACK packed-filename unpacked-filename 

For example, to unpack the PWB.HLP file, insert the disk containing the file in drive A: and 
type: 


UNPACK A:PWB.HL$ PWB.HLP 


To find a particular file on the distribution disks, look at the file PACKING.LST on Disk 1. 


Special Instructions for Microsoft C Users 


If you have installed Microsoft C version 6.0, you should replace the PWB executable files and 
language extensions provided with C with the ones provided with this version of BASIC. 
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BASIC includes a later version of these files that supports the use of BASIC and C together in 
mixed-language programs. 


The PWB extensions for the C language, PWBC.MXT and PWBC.PXT, are provided with 
BASIC, but are not installed by Setup. You should unpack these files individually from the 
BASIC distribution disks and use them to replace the C-language extensions provided with C 
version 6.0. 


How Setup Uses Stub Files 


This section explains how you can produce smaller stand-alone programs using stub files. [i 
you are eager to use BASIC, you can skip this section for now and read it later. 


A “stub file” replaces a BASIC library module with a module that performs little or no action. 
Stub files typically contain a small amount of code. 


The advantage of stub files is that if you know that you will never use a certain feature in your 
program (such as support for VGA screen modes), you can use the stub file to eliminate code 
for that feature. The result is that your programs require less memory and disk space. 


Stub files can be used for BASIC programs that use the BASIC run-time (BRT) module and tor 
BASIC stand-alone executable files. 


Stub Files and the BRT Module 


BASIC programs can use the BRT module to support common routines. The use of the BRT 
module saves disk space by eliminating the need to add library routines to every executable file. 


Setup uses stub files to build the BRT module. It uses a different stub file (see the following 
sections) for each feature you decide not to support. 


Once installation is complete, most stub files have no further effect on the BRT module. You 
can delete them unless you plan to create stand-alone executable files, as described in the next 
section. 


Stub Files and Stand-Alone Programs 


You can produce stand-alone programs with the BASIC compiler by using the /O option. The 
advantage of stand-alone programs is that the BRT module need not be present tor the program 
to run. 


Do not delete stub files if you want to produce stand-alone programs that use the smallest 
amount of memory. When you create a stand-alone program, you can specify stub files on the 
LINK command line. The effect is to cancel or reduce support tor a feature and thus reduce 
executable size. 


For more information on stub files, see Chapter 15, “Optimizing Program Size and Speed.” and 
Chapter 18, “Using LINK and LIB,” in the Programmer's Guide. 
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Graphics Support Stub Files 


The following list summarizes stub files that correspond to items in the second Specify 
Libraries and Run-Time Modules screen, Screen I/O and Graphics Support. Setup uses a 
designated stub file to build the BRT module if the corresponding menu item is turned off. 


Turn this option off 


Full Ctrl-Character 
Text I/O 


Graphic Screen Mode 
Support 


CGA Graphics 
SCREEN Modes I-2 


Hercules Graphics 
SCREEN Mode 3 


Olivetti Graphics 
SCREEN Mode 4 


EGA Graphies 
SCREEN Modes 7-10 


VGA Graphics 


To link with 
this stub file 


TSCNIOsm.OBJ 


NOGRAPH.OBJ 


NOCGA.OBJ 


NOHERC.OBJ 


NOOGA.OBJ 


NOEGA.OBJ 


NOVGA.OBJ 


Having this effect 


Limits the program to text-only 
screen I/O with no support for 
special treatment of control 
characters. Removes support 
for all screen modes other than 
0. 


Removes support for all 
graphics statements and 
SCREEN modes other than 0. 


Removes support for SCREEN 
modes | and 2. 


Removes support for SCREEN 
mode 3. 


Removes support for SCREEN 
mode 4. 


Removes support for SCREEN 
modes 7-10. 


Removes support for SCREEN 


SCREEN Modes I 1—12 modes 1 1—12. 


Miscellaneous Support Stub Files 


The following list summarizes stub files that correspond to items in the third Specify Libraries 
and Run-Time Modules screen: 


To link with 
Turn this option off this stub file 


COMn Device OPEN NOCOM.OBJ Removes support for COM 

and 1/O device filenames. Normally, 
LINK includes support for 
COM port communication 
when an OPEN statement uses 
a filename that is either a string 
variable or starts with “COM.” 


Having this effect 


Getting Started 


LPT Device OPEN NOLPT.OBJ 

and I/O 

INPUT Floating-Point NOFLTIN.OBJ 
Values 

Transcendental Math NOTRNEMm.LIB 
EMS Support for NOEMS.OB§J 
Overlays 

EVENT Trapping NOEVENT.OBSJ 
Full-Power INPUT NOEDIT.OBJ 
Editor 

Detailed Error Messages SMALLERR.OBJ 


Setup 


Removes support for LPT 
device filenames. Normally. 
LINK includes support for LPT 
port communication when an 
OPEN statement uses a 
filename that is either a string 
variable or starts with “LPT.” 


Allows programs to contain 
INPUT, VAL, and READ 
statements without linking in 
floating-point support. Use of 
this stub file assumes you will 
not input floating-point 
constants. 


Removes support for 
transcendental functions. which 
include trigonometric 
functions, exponential 
functions, and the following: 
the CIRCLE statement with a 
start or stop value, and the 
DRAW statement with A or T 
commands. 


Prevents a program linked for 
overlays from using EMS 
memory. The program will be 
forced to swap to disk. This file 
is not built into the BRT 
module, but must be linked 
with your program's object 
files when creating the 
executable file. 

Removes support for EVENT 
trapping. 

Limits editing when a user 
enters data in response to an 
INPUT statement. The user 
will only be able to use 
Backspace to change entries. 
Reduces length of run-time 
error Messages. 
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Other Special Files Installed by Setup 


In addition to stub files, Setup may install two other special files, depending on the 
configuration chosen. Both these files correspond to options in the third Specify Libraries and 
Run-Time Modules screen. As with stub files, Setup builds these files directly into the BRT 
module, but unlike stub files, you must turn the corresponding menu items ov in order to link 
with the files. If you want to use them in a stand-alone program, include them on the command 
line when you link the program. 

To link 
Turn this option on with this file Having this effect 


Math Coprocessor 87.LIB Provides most direct support for 

Required machines that have an 8087-family 
coprocessor installed. This option also 
removes software coprocessor 
emulation, so that programs with 
floating-point calculations can only run 
on computers with a coprocessor. 


Overlays in DOS 2.1 OVLDOS?21.OBJ Required for a program with overlays to 
work under DOS 2.1. 
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Where to Go If You Need Additional Help 


If you need additional help with any of the options in the Setup program, you can use the 
following table to locate information in the printed documentation. If you just need a quick 
overview of the new features in Microsoft BASIC, be sure to read Chapter 1, "New Features.” 
if you haven't already done so. 


For information on 
ISAM 


Near and far strings 


Alternate and emulator 
math 


Overlays 
Compiler options 
Stub files 


Add-on libraries 


Toolboxes 


See 


Programmer's Guide, Chapter 10, “Database Programming with 
ISAM” 


Programmer's Guide, Chapter 11, “Advanced String Storage” 


Programmer's Guide, Chapter 15, “Optimizing Program Size and 
Speed,” and Chapter 16, “Compiling with BC” 


Programmer’ s Guide, Chapter 18, “Using LINK and LIB” 
Programmer's Guide, Chapter 16, “Compiling with BC” 


Programmer's Guide, Chapter 15, “Optimizing Program Size and 
Speed,” and Chapter 18. “Using LINK and LIB” 


BASIC Language Reference, Part 2 


BASIC Language Reference, Part 3, and Programmer's Guide. 
Chapter 6, “Presentation Graphics” 
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Using QuickBASIC Extended 


The QuickBASIC Extended (QBX) environment is a powerful tool for developing BASIC 
applications under DOS. This chapter introduces the QBX environment and covers the 
following information to get you started: 


Starting QBX and using the default editing and command keys. 
Creating and moving around in a program. 
Compiling programs from within QBX. 


Using symbol Help, watches, watchpoints, breakpoints, and Code View support to locate 
and resolve errors in your program. 


Adding items to the menu bar and changing the default editing and command key 
assignments. 


Using the QBX command-line syntax. 


Running QBX 


To start QBX, type the following at the system prompt: 


QBX 


Figure 3.1 shows the QBX environment. 
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File Edit View Search Run Debug Calls Utility Options 
Untitled 


‘Inned iate ————— 


Microsoft (R) QuickBASIC Extended v7.1 (C) Copyright Microsoft Corp, 1982-1998 


Figure 3.1. The QBX Environment 


All environment tasks within QBX can be accomplished by using either the mouse or the 
keyboard. The following table lists commonly used key combinations by category and task. 


Category To do this Press 
Edit Open a program . Alt+F, O 
Save a program Alt+F, S 
Select text Shift+direction key 
Copy selected text Ctrl+Ins 
Cut selected text Shift+Del 
Cut a single line Ctrl+Y 
Paste copied or cut text Shift+Ins 
Search for selected text Ctrl+/ 
Repeat last search F3 
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Debug Execute program Shift+F5 


Execute to cursor position = -F7 


Execute next statement F8 

Execute next procedure FIO 

Continue execution FS 

Add instant watch Shift+F9 

Set/clear a breakpoint F9 
View/Windows Next window F6 

Previous window Shift+F6 

View aSUB F2 

View the next SUB Shift+F2 


Display/hide output screen F4 


Help Help ona topic Fl 
Help on using Help Shitt+F 1 
Exit Help Ese 
Redisplay last Help Alt+F] 


Writing a Program 


After you start QBX, you can immediately begin writing a program. As you enter BASIC 
functions and statements, QBX interprets them and checks the syntax of each line. If you make 
a syntax error, QBX displays an error message dialog box and you must choose OK or press 
Esc to continue. QBX only checks for errors in syntax; to detect errors in logic, you must run 
your program. For example, type the following: 


Now = TIMES 
Press F5 to execute the program. QBX highlights TIMES and displays a “Type mismatch” 
error. Choose OK and correct the line to read: 


NowS = TIMES 


Now the program will execute without an error. 


QBX organizes your program by separating different procedures (SUBs and FUNCTIONS). 
When you save your program, QBX automatically adds DECLARE statements as needed. For 
example, type the following: 


SUB PrintTime 
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When you press Enter, QBX creates a new procedure with SUB and END SUB statements in 
the current window as follows: 


UB PrintTime 


To see the organization of the program, press F2. QBX displays the View SUBs dialog box. 
This dialog box lets you move between procedures and the main module of your program. Press 
Ese to return to the PrintTime procedure. 

Add the following infinite loop between the SUB and END SUB statements: 


DO 
CLS 
LOCATE 2, 1 
PRINT "The time is: "; TIMES; 
SLEEP 1 
LOOP 


Now choose Split from the View menu to open another window. Display the main module in 
the top window by typing Shift+F2 (View Next SUB). After the last statement in the main 
module, type: 


CALL PrintTime 


Run the program by pressing F5. 


Press Ctrl+Break to interrupt the infinite loop and return to QBX. QBX highlights the last 
instruction executed (in this case, LOOP). 


To save the program you just created: 
1. From the File menu, choose Save. 


2. Type the filename TIME.BAS, select Text Format, and press Enter. 
QBX saves the file as text. Text format files can be used by PWB, Code View, and other 
tools. Binary format files can only be used by QBX and the BASIC Compiler. 


Exit QBX by choosing Exit from the File menu. You can view the file you just saved by typing 
the following command from the command line: 


TYPE TIME.BAS 
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The system displays the file as follows: 


DECLARE SUB PrintTime () 
NowS = TIMES 
CALL PrintTime 


SUB PrintTime 

DO 
LOCATE 
PRINT "The time is: " + TIMES 
SLEEP 1 


Notice that QBX adds a DECLARE statement and puts procedures after the main module in 
the file when it saves the file. 


Other Statements Added by QBX 


In addition to the DECLARE statement, QBX automatically adds a DEFrype statement to 
procedures under certain conditions. For example, if you start your program with a 
DEFINT A-Z statement, QBX adds a copy of that statement to the beginning of each new 
procedure you create. 


If your program has existing procedures when you add a DEFrype statement to the main 
(calling) module, those procedures are not changed. Only new procedures get the automatic 
DEF type statements. 


Since the default data type in BASIC is single-precision, QBX will add a DEFSNG statement 
to any previously existing procedures that did not already have a DEFrype statement. These 
statements can only be seen by saving the file as text and viewing it outside QBX. For this 
reason, it is a good idea to start your program with a DEFrype statement. 


Using the Immediate Window 


The Immediate window at the bottom of the screen in QBX is a useful tool for executing a few 
lines of BASIC code without running the currently loaded program. Each line that you type in 
the Immediate window is executed when you press Enter. For example: 


Run QBX. Press F6 to move the cursor to the Immediate window, and type: 
CLS 
PRINT "Today's date is: " + DATES 


Each time you press Enter at the end of a line, QBX executes that line of code and displays the 
output screen. You can cut lines from your program and paste them into the Immediate 
window. You can then scroll to the beginning of the pasted line and execute them one at a time 
by pressing Enter after each, 
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Lines typed in the Immediate window are not saved with your program. When you exit QBX, 
the Immediate window ts cleared. 


Using Quick Libraries 


QBX uses special-format libraries called Quick libraries to make common routines available 
within the environment. To use a Quick library, you must specify it with the /L option when 
you start QBX. For example: 


This command line starts QBX and loads the Presentation Graphics Quick library. The 
Presentation Graphics routines will be available to programs as you work in the environment. 
For more information on Quick libraries, see Chapter 19, “Creating and Using Quick 
Libraries.” in the Programmer's Guide. 


Quick libraries created for QuicKBASIC version 4.5 or earlier must be recreated from the 
original source code, and non-BASIC routines included in Quick libraries may need rewriting 
or relinking. For programming considerations when writing Quick libraries and instructions on 
creating Quick libraries, see Chapter 19, “Creating and Using Quick Libraries.” in the 
Programmer’ Ss Guide. 


To compile a program from QBX, load a BASIC source file and choose Make EXE from the 
Run menu. Figure 3.2 shows the Make EXE File dialog box that QBX displays. 


Make EXE File 


EXE File Nane: ffest.xe | 
EXE Type Target Environment 

(+) Stand-Alone EXE /O| |(*) DOS or OS/2 Real Mode /Lr 

( ) EXE Requiring BRT Module ( ) 08/72 Protected Mode “Lp 


Speed Size/Capacity 
(+) 86x87 or Emulator Math /FPi ( ) Par Strings 

( ) Alternate Math /FPa| |(*) Near Strings 

{ 1] Code Generation for 286 /G2} |{ ] Disable String Compression /S 
(X] Quick Call Optimization /0t 


Debug 
{ ] Run-Time Error Checking Ai) 
{ ] CodeView Information 42i 


/Fs 


Additional Options: 


< Make EXE and Exit > <« Cancel > < Help > 


« Make EXE > 


Figure 3.2 Make EXE File Dialog Box 


26 Getting Started 


Using QuickBASIC Extended 


By default, QBX uses the compiler options that cause your compiled program to run the way 
that it is interpreted within QBX. If a Quick library is loaded, QBX uses /O, /Ot, /Fs. /Lr. /FPi. 
/T, and /C:512 by default. If a Quick library is not loaded, QBX uses /O. /Ot. /Lr. /FPa. /T. and 
/C:512. For descriptions of the BASIC Compiler options, see online Help or Chapter 16, 
“Compiling with BC.” in the Programmer's Guide. 


To change these defaults, you can select any of the displayed compiler options or you can type 
additional options in the Additional Options field. 


When you select Make EXE from the Make EXE File dialog box, QBX shells to DOS and runs 
the BASIC Compiler and LINK to build the executable file. If you have a Quick library loaded. 
QBX links your program with the object module library (.LIB) with the same base name as the 
loaded Quick library (.QLB). 


If an error occurs when compiling or linking, the build halts and the error is displayed: you can 
press any key to return to QBX. 


If the build is successful, you are returned to QBX. 


Debugging a Program 


To help locate errors in program logic, QBX provides the following features: 
= Symbol Help 

a Watches 

a Watchpoints 

a Breakpoints 


= CodeView support 


Symbol Help 


When you ask for Help on a symbol, QBX displays a schematic of where and how that symbol 
is used in your program. Figure 3.3 shows the Help screen that is displayed when you ask for 
Help on the Answer symbol in the BOOKLOOK.BAS program. 
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File Edit View Search Run Debug Calls Utility Options He lp 
HELP: answer ———————________|| 
answer is a symbol that is used in your program as follows! 


C:NBC7\SRC\BOOKLOOK . BAS 
variable of type: INTEGER 


FUNCTION AddOne 
parameter of type: INTEGER 


SUB CheckPosition 
parameter of type: INTEGER 


FUNCTION Get Input 
[ variable of type: STRING 


FUNCTION HighKeys 
[ parameter of type: STRING 


r C:\BC7\SRC\BOOKMODZ . BAS 
BOOKLOOK .BAS ————————___________|t 
IF answer <¢ UNDO THEN ’ Excludes UNDOALL & INVALIDKEY too 
Immediate 
<Shift+Fi=Help> <F6=Window> <F2=Subs> <F5=Run> <F8=Step> | 06677 :611 


Figure 3.3 Symbol Help 


Symbol Help is useful for resolving type mismatch errors and duplicate symbol names. Getting 
Help on a symbol makes it easy to determine a symbol’s data type and the procedures in which 
itis used. 


Watches 


Watches let you observe the value of an expression as your program executes. This is especially 
helpful when your program yields unexpected results. Placing a watch on an expression and 
stepping through the program can help you locate where the problem is occurring. 


To add a watch: 
1. Select the expression you want to observe. 


2. From the Debug menu, choose Add Watch. 
The expression’s name and current value are displayed in a one-line window immediately 
below the menu bar. 


As you run your program, QBX updates the value in the Watch window whenever the value of 
the expression changes. For example, seta watch on N*% in the following lines of code: 

FOR Nt = 0 to 10 STEP 5 

NEXT N® 


Step through the procedure by pressing F8 five times. The value of N' displayed in the Watch 
window changes from 0 to 5 to 10. 
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You can set an instant watch to view the current value of an expression without adding a watch. 
An instant watch shows only the current value of the expression. 


To set an instant watch: 
1. Select the expression to view. 


2. From the Debug menu, choose Instant Watch. 
The current value of the expression is displayed in a dialog box. 


3. Choose Cancel to exit the dialog box without adding a watch or press Enter to add a wateh 
for the expression. 

To remove a watch, choose Delete Watch from the Debug menu, then select the watch to 

remove. 


To remove all watches, choose Delete All Watch from the Debug menu. 


Watchpoints and Breakpoints 


*“Watchpoints” are conditional statements that stop program execution when an expression is 
true (nonzero). “Breakpoints” are markers that stop program execution at a fixed location in the 
program. Watchpoints and breakpoints make it easier to get to a specific point in the logic or 
structure of the program while debugging. 


To set a watchpoint: 

1. Select the expression to watch. 

2. From the Debug menu, choose Watchpoint. 
When you run the program by pressing F5, QBX will halt the program and take you to the 
current statement as soon as the value of the expression becomes nonzero. 

To remove a watchpoint: 

1. From the Debug menu, choose Delete Watch. 

2. Select the watchpoint to remove and press Enter. 

To set a breakpoint: 

1. Place the cursor on a line of code where you want the program to stop eXecuting. 


2. From the Debug menu, choose Toggle Breakpoint. 
When you run the program by pressing F5, QBX will halt the program as soon as it reaches 
line of code with the breakpoint. 


To remove a breakpoint, place the cursor on the line with the breakpoint and choose Toggle 
Breakpoint from the Debug menu. 
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CodeView Support 


To use CodeView with programs created in QBX, you must save the source file in text format. 
Code View cannot interpret files saved in QBX binary format. 


After saving your program, compile it specifying the Code View option (/Zi or /Zd). You can 
then load the file into Code View trom the command line. For information on getting started 
with Code View, see Chapter 5, “Using CodeView.” For detailed information about the 
Code View environment and how expressions are evaluated in Code View, see the CodeView 
online Help. 


Customizing the Environment 


You can add items to the menu bar and remap key assignments within the QBX environment. 


Adding Items to the Menu Bar 


To add an item to the menu bar: 

1. From the Utility menu, choose Customize Menu. 

2. Select Add from the Customize Menu dialog box. 

3. Type the appropriate information in the displayed fields, and choose OK. For information 


about the field in the Customize Menu dialog box, press F1. 


The new item will appear on the Utility menu. 


Remapping Key Assignments 


The default QBX editing and command keys can be modified by loading one of the following 
files with the /K: option when you start QBX: 


Load this file To change settings to those for this editor 
ME.KEY Microsoft Editor _ 
BRIEF.KEY BRIEF 

EPSILON.KEY Epsilon 

QBX.KEY QBX 


For example, to change the default settings to those of the Microsoft Editor, start QBX with the 
following command line: 


QBX /k:ME.KEY 


When you change the default key settings, the change is saved in QBX.INI and those settings 
become the new default. 
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You can further customize these key assignments by using the MKKEY utility as follows: 


1. Decode the key assignment file. For example: 


MKKEY -c ba 


OBX.KEY -o MYKEY.TXT 


2. Edit the decoded file (in this case, MYKEY.TXT). 


io) 


MKKEY -c ab 


Encode the modified key assignment file. For example: 
MYKEY.TXAT -o MYKEY. KEY 


4. Load the new key assignment file in QBX. For example: 


OBX /k:MYKEY.KEY 


For more information on customizing key assignments, see the online Help topic “Configuring 
Keys” from the Help table of contents in QBX. For more information about MKKEY. see 
Appendix C in the BASIC Language Reference. 


Controlling the Environment 


You can control various aspects of the environment by using the QBX command-line options. 
The QBX command line has the following syntax: 


QBX |leptions]] programname || [/CMD string] 


/B 


/C: buffersize 


/Ea 


/E:n 


/Es 


IG 

/H 

/K:[[keyfile]] 

/L |libraryname || 


Short description 


Allows dynamic arrays of records, fixed-length strings, and 
numeric data to be larger than 64K each. 


Displays QBX in black and white. 


For use with the OPEN COM statement. Sets the size of the buffer 
receiving data with an asynchronous communications card, The 
default ts /C:512. 


Allows arrays in expanded memory. Do not use /Ea with the /Es 
option. 


Limits the amount of expanded memory reserved for QBX use. It 
/E:n is not specified, all available expanded memory may be used. 


Shares expanded memory between QBX Quick library and mixed- 
language routines that make use of expanded memory. 


Sets QBX to update a CGA screen as quickly as possible. 
Displays the highest resolution possible on your hardware. 
Specifies a user-configurable key file to be loaded into QBN. 


Loads a Quick library. If /ibraryname is not specified, the detault 
Quick library (QBX.QLB) is loaded. 


Getting Started 31 


Chapter 3 


32 


/MBF Causes the QBX conversion functions to treat IEEE-format 
numbers as Microsoft Binary format numbers. 

/Nofrills Makes additional memory available for program use by reducing 
the functionality of the environment. 

/NOHI Allows the use of a monitor that does not support high intensity. 
Not for use with COMPAQ laptop computers. 

ICMD string Passes string to the COMMAND$ function. This option must be 


the last option on the line. 


Complete descriptions of the QBX options are available through online Help or in Appendix C 
in the BASIC Language Reference. 
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Using Programmer’s WorkBench 


The Programmer's WorkBench (PWB) is an advanced development environment that features a 
powerful editor and integrates the compiler, LINK, NMAKE, and the CodeView debugger. 
PWB is intended for tasks, such as developing under OS/2, that are not supported by QBX. 
Unlike QBX, PWB does not interpret BASIC code. This means that some features available in 
QBX, such as the Immediate window and executing a program line-by-line, are not available. 
In PWB, you must use Code View to debug programs. 


This chapter explains how to perform the following tasks: 


mw Starting PWB and using keyboard commands. 

ws Loading and saving a file, setting or clearing a program list, and using special features 
(such as marks and anchors) to help you write and modify your programs. 

# Selecting build options and creating an executable file. 

ws Preparing a file for debugging, viewing compiler errors, using the source browser, and 
invoking Code View. 

= Changing the default settings and key assignments, creating macros, and reducing the time 
it takes PWB to load. 

a Using the PWB command-line syntax. 

Note Setup installs PWB only if you choose to install mixed-language tools from the Specify Files to 


Install menu during Setup. If you did not choose mixed-language tools and you wish to use 


PWB, you should run Setup again with the mixed-language tools option chosen. 
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Running PWB 


impor fani 


To start PWB for the first time, type: 
PWB 


Figure 4.1 shows the PWB environment. 


File Edit View Search Make Run Options Browse 
<UNTITLED> 


4 


4! 


|pseudo 60801 .801 


| <General Help> <Fi=Help> <Alt=Menu> 


Figure 4.1 The PWB Environment 


PWB includes extensive online Help. If you request Help and get an error message indicating 
that no Help files were open or that they could not be found, check your HELPFILES 
environment variable. HELPFILES can be set by running NEW-VARS.BAT (DOS) or 
NEW-VARS.CMD (OS/2) from the command line before starting PWB. HELPFILES can also 
be set from within PWB by choosing Environment trom the Options menu. If you set 
HELPFILES from within PWB, that setting will not have an effect in Code View. 
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Within PWB, environment tasks can be accomplished by using either the mouse or the 
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keyboard. The following table lists commonly used default key combinations by category and 


task: 
Category 
Edit 


To do this 

Select text 

Copy selected text 

Cut selected text 

Cut a single line 

Paste copied or cut text 
Undo previous edit 
Redo edit 

Search forward 


Search backward 


File operations 


Debug/Browse 


Windows 


Open a program 
Save a program 


Exit (save changes) 


Quit (abandon changes) 


Refresh (abandon changes) 


Load previous file 


Shell to system 


Next definition/reference 


Previous definition/reference 


Next build error 


Previous build error 


Next window 
Previous window 
Resize a window 


Maximize a window 


Press 
Shift+direction key 
Ctrl+Ins 

Shift+Del 

Ctrl+Y 

Shift+Ins 
Alt+Backspace 
Ctrl+Backspace 

F3 

F4 


Alt+F, O 
Shift+F2 
Alt+F4 
F9, F8 
Shift+F7 
F2 
Shift+F9 


Ctrl+Num+ 
Ctrl+Num- 
Shift+F3 
Shift+F4 


Fe 
Shitt+F6 
Ctrl+F& 


Ctrl+F 10 
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Help | . Get Help on a topic 
View table of contents Shitt+F 1 
Exit Help Esc 
Redisplay last Help Alt+F1 


Writing a Program 


After you start PWB, you can immediately begin writing source code in the window that 
appears. PWB supports programming in BASIC, C, and other Microsoft languages. Unlike 
QBX. PWB does not interpret your program as you write it. Also unlike QBX, PWB does not 
check your BASIC syntax or automatically add DECLARE statements as you write your 
program. To check syntax in PWB, you must compile your program and view the compile 
results. For more information on how to do this, see the sections “Compiling and Linking a 
Program” and “Debugging a Program” later in this chapter. 


Loading and Saving a File 


To load a file in PWB, you can either type the filename on the command line when you start 
PWB or choose Open from the File menu within PWB. 


If you are planning to use PWB in combination with QBX, you must save your source files in 
text format from QBX before you try to load them in PWB. PWB cannot use files saved in 
QBX binary format. 


To save a file, choose Save from the File menu. 


PWB maintains a history of the files you have opened, which is displayed at the bottom of the 
File menu. To return to a file displayed in this list, choose its name from the File menu. Figure 
4.2 shows the File menu with several files in history. 
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Open... 

Merge... 

Next F8 
Save Shift+F2 
Save As... 

Save All 

Close 


Print... 
DOS Shell Shift+F9 


Exit Alt+F4 


1 NEW.BAS Alt+i 
2 BAR.BAS Alt+2 
3 BALLXOR .BAS Alt+3 
4 ADAPTER .BAS Alt+4 
5S TERMINAL .BAS 


—— File History 


Figure 4.2 File History on the File Menu 


When you edit a file and then exit PWB, the environment saves a list of the files you worked on 
in a special file named CURRENT.STS. PWB creates CURRENT.STS in the first directory 
indicated by your INIT environment variable. The next time you run PWB, it automatically 
opens the last file you worked on unless you explicitly specify a filename on the command line 
or use the /D or /DS options. For PWB command-line syntax and options, see the section 
“Controlling the Environment” later in this chapter. 


Navigating in a File 


PWB provides marks and anchors to help you navigate and edit large files. A “mark” Is an 
invisible placeholder that you can set at a specified location in a file to go to that location 
quickly in the future. An “anchor” is a placeholder that determines the boundary of a block ot 
selected text to cut, copy, or delete. 


Setting and Using Marks 
To set a mark: 


1. Place the cursor at the location you want to mark, then choose Define Mark trom the Search 
menu. 
PWB displays the Define Mark dialog box. 


2. Type a name that you want to assign to the mark and press Enter. Note that spaces are not 
allowed in mark names. 
To go to a mark: 


1. From the Search menu, choose Goto Mark. 
PWB displays the Go To Mark dialog box. 


2. Select the mark from the displayed list and choose OK. 
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Creating and Using a Mark File 


Marks created as shown in the preceding section are temporary and are erased when you exit 
PWB. To create marks that can be reused, you must create a mark file or select an existing one 
before setting your marks. 


To create a new mark file: 


1. From the Search menu, choose Set Mark File. 
PWB displays the Set Mark File dialog box. 


2. Type the name of the mark file you wish to create and press Enter. (The mark file should 
have an .MRK file extension to help you identify it in the future.) 
PWB displays a dialog box asking if you want to create the file. 


3. Choose Yes. 


To select an existing mark file: 


1. From the Search menu, choose Set Mark File. 
PWB displays the Set Mark File dialog box. 


2. Select a mark file from the displayed list and choose OK. 
After you create a new mark file or select an existing one, it becomes the current mark file and 


any temporary marks are cleared. When you set new marks, they are added to the current mark 
file by default. 


Setting and Using Anchors 
Anchors help you select large blocks of text to cut, copy, or delete. 


To set an anchor, place the cursor at the position you wish to anchor and choose Set Anchor 
from the Edit menu. You can only set one anchor at a time: moving the cursor and choosing Set 
Anchor again resets the anchor to the new position. 


To select text between the current cursor position and the anchor, choose Select To Anchor 
from the Edit menu. PWB highlights the selected text. 


Programming with Multiple Files 


To work on a project containing multiple files, you must create a program list. A “program list” 
is a special PWB file that contains the build instructions and filenames for a project. 


To create a program list: 


1. From the Make menu, choose Set Program List. 
PWB displays the Set Program List dialog box. 
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2. Type the name of the program list you wish to create and press Enter. (The filename should 
have an .MAK file extension to help you identify it in the future.) 
PWB displays a dialog box asking you if you want to create the file. 


3. Choose Yes. 
PWB displays the Edit Program List dialog box. 


4. Select the files to include in the project from the displayed list. Do not select BASIC 
include files (.BI), since they will be included when the program is compiled. 


5. Choose OK when you are done. 


Build options are maintained in a state file that is maintained along with the .MAK file. A 
“state file” is a file containing information about the PWB editing session, such as current build 
options and file history. The state file maintained with a .MAK file has the same base name as 
the .MAK file, but has a .STS filename extension. When you set a program list, build options 
revert to those last saved in the state file. For information on setting build options. see the 
section “Compiling and Linking a Program” later in this chapter. 


To use an NMAKE .MAK file in PWB, follow the procedure used to create a program list. but 
select the Use as a Non-PWB Makefile checkbox in the Set Program List dialog box before you 
press Enter in step 2. 


PWB .MAK files are not compatible with QBX .MAK files and vice versa. If you are working 
on a project in both environments, you should create a different .MAK file for each 
environment. 


Compiling and Linking a Program 


Executable files can be created directly from the PWB environment. Options can be saved tor 
debug and release versions of the executable file. All of the environment. compiler. and LINK 
options are set from the Options menu. 


Changing Environment Variables 


To change environment variables from those in effect when PWB was run: 


1. From the Options menu, choose Environment. 
PWB displays the Environment Options dialog box. 


2. Type the new environment variables in the fields provided. Press Tab to move to the next 


option, and press Enter when you are done. 


The new environment variables take effect immediately and remain in effect until you exit 
PWB. To make permanent changes to environment variables, edit your AUTOEXEC.BAT file 
(DOS) or your CONFIG.SYS file (OS/2). 
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Setting Debug or Release Version 


PWB maintains lists of debug and release options for compiling and linking a program. By 
default, debug options create an executable file for use with Code View: release options create 
an optimized executable file without Code View information. Setting release or debug version 
makes it easy to switch between the two sets of options quickly. 

To set whether the executable file will be a debug version or a release version: 


1. From the Options menu, choose Build Options. 
PWB displays the Build Options dialog box. 
2. Select Debug or Release from the dialog box. 


3. Choose OK. 


Debug and release version options are set from the compiler and LINK options dialog boxes. 
To change compiler and LINK options for debug or release versions, see “Setting Compiler 
Options” and “Setting LINK Options” later in this chapter. 


Setting Main Language and Initial Build Options 


Since PWB is a mixed-language programming environment, many of the build options that are 
valid in some languages are not valid in others. PWB provides you with a way to set a main 
programming language and to create default build options based on the target environment. 
When working with BASIC, you should always leave Main Language set to BASIC. When 
working exclusively in another language, such as C, you will want to change the Main 
Language. 


c 


To change the Main Language: 


1. From the Options menu, choose Build Options. 
PWB displays the Build Options dialog box. 


2. Select Set Main Language. 
PWB displays the Set Main Language dialog box. 


3. Select a language from the displayed list, and choose OK. 


4. Select Set Initial Build Options box. 
PWB displays the Set Initial Build Options dialog box. 


5. Select the line from the displayed list that best describes the executable tile you want to 
build, and choose OK. 


6. Choose OK again. 
Three valid initial build options are provided for BASIC. You can save your current build 


options to create a new group of initial build options that you can use with future projects. To 
create a new group of initial build options tor BASIC: 


1. Set Main Language to BASIC (see the preceding procedure). 
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Set the build options. These include the settings for the debug and release versions of 
compiler, LINK, and Source Browser options. 


3. From the Options menu, choose Build Options. 
PWB displays the Build Options dialog box. 


4. Select Save Current Build Options. 
PWB displays the Save Current Build Options dialog box. 


5. Type aname to identify your current build settings, and press Enter. 
6. Choose OK. 


PWB saves initial build options in your state file. (For more information on state files. see the 
section “Reducing Load Time” later in this chapter.) After initial build options are saved. thes 
are available from the Set Initial Build Options dialog box. 


Setting Compiler Options 
To set the BASIC compiler options within PWB: 


1. From the Options menu, choose BASIC Compiler Options. 
PWB displays the BASIC Compiler Options dialog box. 


2. Select the appropriate displayed options, then select Set Debug Options or Set Release 
Options. 


3. Select the appropriate options from the BASIC Compiler Debug/Release Options dialog 
box, and choose OK. 


4. Type any additional options you wish to specify in the Additional Options field, and choose 
OK. 


It is possible to set options in the Additional Options field that conflict with the options 
specified in the BASIC Compiler Options dialog box. Conflicting options will cause the 
compile to fail. 


Setting LINK Options 
To set LINK options within PWB: 


1. From the Options menu, choose LINK Options. 
PWB displays the LINK Options dialog box. 


2. Select the appropriate displayed options, then select Set Debug Options or Set Release 
Options. 


3. Select the appropriate options from the LINK Debug/Release Options dialog box. and 
choose OK. 


4. Type any additional options or libraries you wish to specify in the Additional Libraries and 
Additional Options fields, and choose OK. 
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Some LINK options, such as /INCREMENTAL and /TINY, are not valid for BASIC and will 
cause the build to fail. For a list of the valid LINK options and their uses, see Chapter 18, 
“Using LINK and LIB.” in the Programmer’ s Guide. 


Building an Executable File 


PWB offers four choices from the Make menu for building an executable file. These selections 
allow you to: 


e Compile or compile and link a single file. 
a Compile changed files and relink with unchanged object files in a project. 
a Compile and link all files (changed and unchanged) in a project. 


For information on creating a project, see the section “Programming with Multiple Files” 
earlier in this chapter. 


Compiling a Single File 


Compiling a single file can be used as a first step in debugging a new program or as preparation 
for compiling and linking files in a program list. 


To compile a single file: 
1. Open the file to be compiled. 


2. Set the compiler options. 


or) 
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From the Make menu, choose Compile File. 
PWB compiles the file. Any errors, are displayed in the Compile Results window. 


4. PWB displays a dialog box confirming that the compile has completed. Select one of the 
buttons or press Esc to return to the active window. 


Compiling and Linking a Single File 

To compile and link a single-file program: 

I. Open the file to compile and link. 

2. Set build, compiler, and link options as needed. 


From the Make Menu, choose Build or Rebuild All. The Build command recompiles the 
file if it has changed since it was last compiled, then links the file with the appropriate 
library to create an executable file. Rebuild All compiles the file whether or not it has 
changed, then links the file with the appropriate library to create an executable file. 

If the build fails, PWB displays compile or LINK errors in the Compile Results window. 


‘ow 
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4. PWB displays a dialog box confirming that the build has completed. Select one of the 
buttons or press Ese to return to the active window. 
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Compiling and Linking Files in a Project 


PWB gives you two options for compiling and linking the files in a project: you can recompile 
only files that have changed and link with unchanged object files, or compile and link all files 
whether or not they have changed. 


To compile and link files in a project: 


1. Set or create a program list for the project (see “Programming with Multiple Files” earlier 
in this chapter). 


2. Set build, compiler, and link options as needed. 


3. From the Make Menu, select Build or Rebuild All. Build compiles only changed files in the 
project and links them with existing (unchanged) object files. Rebuild All compiles and 
links all files in the project. 

If the build fails, PWB displays compile or LINK errors in the Compile Results window. 


4. PWB displays a dialog box confirming that the build has completed. Select one of the 
buttons or press Esc to return to the active window. 

The preceding procedure uses the same compiler options for all files in the program list. To 

build a project using different compile options for a single file within that project: 

1. From the Make menu, choose Clear Program List. 

2. From the File menu, choose Open to open the file to compile. 

3. Set the compiler options for the file. 

4. From the Make menu, choose Compile. 

5. From the Make menu, choose Set Program List and select the program list for the project. 
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. From the Make Menu, choose Build. 
PWB does not recompile the file you compiled in step 4, since it has not changed. It will, 
however, recompile any changed files using the compile options last set for the program 
list, then link the objects with the appropriate library to create an executable file. 


Debugging a Program 


PWB provides the following diagnostic tools to help you locate errors, debug. and maintain 
your programs: 


= Compile Results window 
= Source browser 


ws CodeView support 
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Viewing Compiler Results 


If errors occur When you compile or build a program, PWB displays the errors in the Compile 
Results window, as shown in Figure 4.3. 


File Edit View Search Make Run Options Browse He lp 


|: C:\BC7\SRC\NEW . BAS It] 


ATA 23, -45, 6, 5S, 1,12, 7, 1, -9,8 


LS 

EDIM X(1 TO 16) AS INTEGER ’ Create dynamic array. — Program Window 

OR I~ = 1 TO 10 ’ Read in data. 
READ X(1x) 

EXT Ix 


see esse 
+++ PWB  [C:\BC7\SRC] Compile NEW.BAS t 


be /Z /0 /G2 /Fpi “Lr /D /Zi NEW.BAS, NEW.obj; | 
icrosoft (R) BASIC Compiler Version 7.18.05 (Beta) 
opyright (C) Microsoft Corporation 1982-1998. All rights reserved. 


—— Compile Results 
Window 


5858 Bytes Available 
5376 Butes Free 


8 Warning Error(s) 
8 Severe Error(s) 


t 


fl 


| 
<Fi=Help> <Alt=Menu> <F6=WINDOW> [pseudo -R 66001 .681 


Figure 4.3 Compile Results Window 
PWB automatically takes you to the location in your source file where the first error occurred. 
To go to the next error, press Shift+F3. To return to the previous error, press Shift+F4. 


To close the Compiler Results window, choose Compile Results from the View menu. 


Using the Source Browser 

The PWB Source Browser provides a way to view relationships within a program and to 
quickly locate specific procedures, variables, and constants. 

In order to use the Source Browser, it must be turned on before compiling and linking. Once the 
Source Browser is on and the program has been compiled and linked, the selections on the 
Browse menu become active. The Browse menu is shown in Figure 4.4. 
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Browse 


Goto Definition... 
Goto Reference... 
View Relationship... 
List References... 
Call Tree... 
Outline... 


Next Ctrl +Num+ 
Previous Ctr] +Nun- 


Case Sensitive 
Split Windows 


Figure 4.4 Browse Menu Selections 


Browser Terminology 


Since the Source Browser can be used with programs written in languages other than BASIC. 
some of the terms the Browser uses to refer to symbols may not be familiar. Keep in mind the 
following equivalents: 


Source Browser term BASIC equivalent 

Functions Oo Procedures (SUBs and FUNCTIONS) 
Types User-defined types 

Macros Constants 


Turning On the Source Browser 


To generate information for the PWB Source Browser, you must turn on browse information 
and compile the program: 


1. From the Options menu, choose Browse Options. 
PWB displays the Browse Options dialog box. 


2. Select Generate Browse Information and any additional options. 

3. Choose OK. 

4. Compile and link the program. 

By default, PWB creates full browser information by compiling with the /FBx option. The /FBx 
option generates browser information for global and local definitions. To generate information 


for global definitions only, thus reducing the size of the resulting Browser files, you can 
perform the following steps before compiling and linking: 


1. From the Options menu, choose BASIC Compiler Options. 
PWB displays the BASIC Compiler Options dialog box. 


2. Select Set Debug Options or Set Debug/Release Options. 
3. From the Set Options dialog box, choose Restricted Browse Info /FBr, and choose Ok. 


4. Choose OK again. 
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When you compile and link from PWB with the Source Browser turned on, the BASIC 
compiler generates a Browser information file with an .SBR extension. PWB then uses 
PWBRMAKE.EXE to convert this file into one which the Browser can read. This new file has 
a .BSC file extension. 


Locating Program Symbols 


The Source Browser helps you quickly find where procedures, variables, user-defined types. 
and constants are defined and referred to. 


To locate a definition: 


1. From the Browse menu, choose Goto Definition. 
PWB displays the Goto Definition dialog box as shown in Figure 4.5. 


2. Select the item you wish to locate from the Names list box. 
PWB displays the locations where the definition occurs in the Defined in: list box. 


3. Select the occurrence of the definition you wish to go to from the Defined in: list box. 


4. Choose OK. 
PWB takes you to the location in the file where the selected definition occurs. 


Goto Definition 
Nasa? FANSUED scum asiaseanneniasiones srantemininte Series le stra anatase eRe oe 
File: 


Names 


ADJUST INDEX BOOKLOOK.bas (62) t 
ADJUST INDEXS$ BOOKLOOK.BI (127) | 
ALERTS BOOKLOOK .bas (374) 
ALINE BOOKLOOK .bas (562) 


reas 


ANSWER” 
ANYRECORDS 
ARGUMENT 
ARGUMENTy 
AUTHORF LELD 


< OK > <Cancel> < Help > 


Figure 4.5 The Goto Definition Dialog Box 


To locate a reference: 


1. From the Browse menu, choose Goto Reference. 
PWB displays the Goto Reference dialog box. 


2. Select the item to locate from the Names list box. 
PWB displays the locations where the reference occurs in the Referenced in: list box. 
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3. Select the occurrence of the reference you wish to go to from the Referenced in: list box. 
4. Choose OK. 

PWB takes you to the location in the file where the selected reference occurs. 
To go to the next reference or definition of a symbol, press Ctrl+Keypad Plus Sign (+). 


To return to the previous reference or definition of a symbol, press Ctrl+Keypad Minus Sign (-) 


Viewing Relationships Between Symbols 


The Source Browser helps you view relationships between procedures, variables, user-defined 
types, and constants. These relationships include where a symbol is detined and used. where a 
procedure is called, what calls are made by a procedure or module, etc. 


To view how a single symbol relates to the rest of the program: 


1. From the Browse menu, choose View Relationship. 
PWB displays the View Relationship dialog box, as shown in Figure 4.6. 


2. Select Program Symbols from the Operation list box. 

3. Select the symbol you want to view from the list box. 

4. Select the operation you want to perform from the Operation list box. 
5 


. Choose OK. 


To redisplay all the symbols, select Program Symbols from the Operation list box and choose 
OK. 


View Relationship 


Nane:[ 


List: Program Symbols (422 items) 


ADDED (variable) 
ADDONES (function) 
ADDONEx (function) 
ADDRECORD (constant) 
ADJUSTINDEX (function) 
ADJUSTINDEXS (function) 
ALERTS (variable) 
ALERTS (variable) 
ALINE (constant) 
ANSWER (variable) 
ANSWER (parameter) 
ANSWERS (variable) 
ANSWER’ (parameter) 
ANYRECORDS (variable) 
ARGUMENT (parameter) 


«History...» ¢ Goto > 


Figure 4.6 View Relationship Dialog Box 


Operation: 


Progran Files 
Program Symbols 
Contains 

Calls 

Called By 

Uses 

Used By 

Used In 

Defined In 


only: 
Funct ions 
Variables 
Types 
Macros 


Pattern: [:-- 


<Cancel> < Help > 
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To view a listing of the different types of symbols and where they are used: 


1. From the Browse menu, choose List References. 
PWB displays the List References dialog box. 


nm 
. 


3. Choose OR. 


PWB creates a file named <browse> containing the call tree and displays it in the active 


Select the types of symbols to list. 


window, as shown in Figure 4.7. 


File Edit View Search Make Run Options Browse 
<browse> 
UNCTION CALLED BY LIST 
ADDONES : (BOOKLOOK ) ADDONES [2] 
ADDONEx : (BOOKLOOK) [2] 
ADJUST INDEX: (BOOKLOOK) [2] SEEKRECORD 
ADJUST INDEXS : (BOOKMODZ ) 
BOOKSBORROVED : (BOOKLOOK) [2] 
BOOKSBORROWEDS : (BOOKMOD3) 
BOOKSOUTBOXS : (BOOKLOOK ) 
BOOKS TABLES : (BOOKMOD1) DRAWTABLE 
BORROWBOOK : (BOOKMOD3 ) 
BORROWBOOKE : (BOOKLOOK) [2] 
BORROWED : (BOOKMOD3 ) BORROWED(2Z] 
BORROWEDS : (BOOKLOOK) [3] 
CATCHKEY:: (BOOKMOD3) CATCHKEY”[2] 
CATCHKEY:: (BOOKLOOK ) 
CHANGERECORDS : (BOOKMODZ) CHANGERECORDS [2] 
EDITFIELD(2] 
CHANGERECORD» : (BOOKLOOK ) 
CHECK INDEX : (BOOKLOOK)[2] RETRIEVER(2] 
SEEKRECORD[2] ADJUST INDEX$ : 
> 
<General Help> <Fi=Help> <Alt=Menu> [pseudo RM 06063 .684 


Figure 4.7 Source Browser Reference List 


To view an outline of where procedures are called (referred to as a “call tree”): 


1. From the Browse menu, choose Call Tree. 
PWB displays the Call Tree dialog box. 


2. Select a file to view from the Files list box or a procedure to view from the Functions list 


box. 
3. Choose OK. 


PWB creates a file named <browse> containing the listing and displays it in the active 


window, as shown in Figure 4.8. 
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File Edit View Search Make Run Options Browse 
<browse> 

OOKLOOK. bas 
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| CLEAREM~? 
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} ADDONES(2]... 
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| SHOWMESSAGEx[21? 
| ERASEMESSAGEZ([2 1? 
CHOOSEORDER 

| DRAWTABLE? 

| DRAWINDEXBOX[21? 

| PLACECURSORz? 

| SHOWRECORD? 

| SHOWMESSAGE? 

{ CHOOSEORDER(2]... 

DUPEF IXER 

+ SHOWMESSAGE% (21? 
EDI TCHECK 

| DRAWINDEXBOX? 
GET INPUT 7 : 
scoaarechapastserlabahceriseaetthet istrict if iiss EES AS SS SS eS SSE EE 3 4 


<General Help) <Fi-Help> <Alt=Menu> —— | aaa ..284 


Figure 4.8 Source Browser Call Tree 


To view an outline of a program: 


1. From the Browse menu, choose Outline. 
PWB displays the Outline dialog box. 


2. Select the file to view from the File List list box. 


3. Select the type of symbols you want to include in the outline from the options under the 
Show Only label. 


4. Choose OK. 
PWB creates a file named <browse> containing the outline and displays it in the active 
window, as shown in Figure 4.9. 
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rose) || 
OOKLOOK . bas t 
ADDED (variable ‘:module) 
ADDONES (function: public) | 
ALERTS (variable: local) 
ALERTS (variable ‘module) 
ANSWER (variable:module) 
ANSWER (parameter : local) 
ANSWERS (variable: local) 
ANSWERy (parameter : local ) 
ANYRECORDS (variable:module) 
ARGUMENT (variable: local) 
ARGUMENT» (variable: local) 
ARGUMENT. (variable :module) 
BIGREC (variable :module) 
BIGREC (parameter: local ) 
BOOKLOOK (program ‘:module) 
CHECKED (variable: module) 
CHECKEDOUT (var iable‘module) 
CHECKPOSITION (function: public) 
CHOOSEORDER (function: public) 
DATETOSHOWR (variable ‘module) i 
+ + y Seite 3 e SH eneats if iia te > 
<General Help> <Fi=Help> <Alt=Menu> |pseudo RM 00074 661 


Figure 4.9 Source Browser Program Outline 

By detault, the <browse> file replaces the current program file in the active window. You can 
set PWB to create a new window for the <browse> file by choosing Split Window from the 
Browse menu before viewing symbol relationships. 


Using CodeView 
To start Code View from PWB: 


1. Build an executable file using the Code View options for the compiler (/Zi or /Zd) and 
linker (/CO). These are set by default if you are building a debug version of the program. 
See the section “Setting Debug or Release Version” earlier in this chapter. 

2. From the Options menu, choose Code View Options to set the Code View command-line 


options. 


3. From the Run menu, choose Debug. 
PWB exits and loads Code View. 


When you exit Code View, PWB is restarted. 
For more information on using Code View to debug your programs, see Chapter 5, “Using 
Code View.” 
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Customizing the Environment 


Within PWB you can customize many features of the environment, such as screen colors. editor 
behavior, and key assignments. You can also define new functions as macros and assign them 
to keystrokes. 


Changing Editing Settings 
To change how the environment looks and behaves: 


1. From the Options menu, choose Editor Settings. 
PWB displays the current editor settings in the active window. 


2. Scroll down to see all of the settings. Online Help is available for each of the settings. 

3. Change the settings as appropriate. The new settings take effect when you move the cursor 
to the next line. 

To make the changes permanent, choose Save from the File menu. PWB saves the changes to 

the TOOLS.INI file. If you do not save the changes, they are discarded when you exit PWB. 


To return to the current file, press F2. 


Assigning Keystrokes 


To change key assignments or to assign new functions to keys: 


1. From the Options menu, choose Key Assignments. 
PWB displays the current key assignments in the active window. 


2. Scroll down to see all of the assignments. Online Help is available for each of the editor 
functions. 


3. Change the key assignments as appropriate. The new assignments take effect when you 
move the cursor to the next line. 


To make the changes permanent, choose Save from the File menu. PWB saves the changes to 
the TOOLS.INI file. If you do not save the changes, they are discarded when you exit PWB. 


To return to the current file, press F2. 


The key assignments are divided into sections for each part of PWB. A label at the beginning of 
each section indicates where the assignments are used. For example, the [pwb] tag indicates 
that the subsequent assignments apply to the entire PWB environment; the [pwb-pwbbasic] tag 
indicates assignments that apply only to the BASIC Compiler selection from the Options menu: 
and the [pwb-pwbhelp] tag indicates settings that apply to the online Help system. 


A table of key assignments unused by PWB is included after the [pwb-pwbutils] tag. These kes 
combinations may be used for currently unassigned editor functions or for new functions 
created as macros. 
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Creating Macros 


To record a macro: 
1. From the Edit menu, choose Record On. 
PWB displays the Set Macro Record dialog box. 
2. Type the name you want to assign to the macro in the Name field. 


3. Tab to the Key Assignment field and type the names of the keystrokes you want to assign 
to the macro. If you place the cursor between the braces, { }, and press the key sequence 
you want to assign to the macro, the correct description of the key sequence is displayed in 
the field to the right. 


4, Choose OK. 


Pertorm the actions you want to record. 


wm 


6. Choose Record On again to end the recording. 


To make the recorded macro permanent: 
1. From the Edit menu, choose Edit Macro. 
PWB displays the currently defined macros in the active window. 
2. From the File menu, choose Save. 
3. Press F2 to return to the current file. 
When you make a macro permanent, PWB writes the macro definition and key assignment to 


your TOOLS.INI file. To modify the macro after you have made it permanent, you must edit 
the TOOLS.INI file. 


Examining macro definitions in TOOLS.INI is a good way to learn the syntax of macros. 
Example macros are included in the TOOLS.PRE file included with BASIC. Online Help is 
also available on how to create and modify macros in PWB. 


Reducing Load Time 


When you start PWB, it automatically reads your TOOLS.INI file and a state file named 
CURRENT.STS from the directory defined in your INIT environment variable. Together, these 
files control the editor settings, macro definitions, and key assignments used by PWB. Since 
reading these files takes time, you can reduce load time by: 


w Keeping the PWB entries in TOOLS.INI as short as possible. 
w Keeping CURRENT.-STS as small as possible. 


w Not reading one or both of these files when you start PWB. 
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PWB also automatically loads any extension files it finds whose filenames start with the letters 
“PWB” in the directory from which you start PWB. These extension files make certain 
functions, such as the BASIC Compiler options, available in the environment. You can further 
reduce load time by disabling this auto-load feature and explicitly loading only the extensions 
you need. 


Minimizing TOOLS.INI 


The entries for PWB in your TOOLS.INI file appear after the [pwb] label in that tile. 
TOOLS.INI can be edited and saved in the same way as any other file. Macros and settings that 
you may not use can be commented out by placing a semicolon (:) as the first character on the 
line. Lines that have been commented out are not read when PWB starts and will reduce load 
time slightly. 


Minimizing CURRENT.STS 


PWB creates the CURRENT.STS file to save file history and some editor settings (such as 
build options and file history). This file can be kept small by reducing the number of files you 
keep in history and by keeping the default editor settings. To reduce the number of files PWB 
keeps in history, you can reduce the number assigned to the tmpsav switch after the |pwb] label 
in the TOOLS.INI file. Reducing this number reduces the number of files that can be recalled 
from the File menu without using the Open File dialog box. 


Ignoring TOOLS.INI and CURRENT.STS 


You can prevent PWB from reading TOOLS.INI or CURRENT.-STS or both files by using one 
of the /D options when you start PWB from the command line. The /DS option prevents 
CURRENT.STS from being read. The /DT option prevents TOOLS.INI from being read. The 
/DST option prevents both files from being read. Although these options prevent the 
information in these files from being available to PWB, they can be useful for some 
programming tasks. 


Starting PWB with /DS is especially useful when working with a program list, since PWB 
creates a startup file to save the editor settings for each program list you create. When you set a 
program list, PWB automatically reads the new editor settings from the startup file for the 
program list. This file has the same base name as your .MAK file, but has an .STS filename 
extension. For more information on PWB command-line options, see the section “Controlling 
the Environment” later in this chapter. 
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Loading PWB Extensions Explicitly 


PWB does not automatically load its extensions if you include the /DA option when you start 
PWB trom the command line. This significantly reduces the time it takes to start PWB, but also 
limits the features that are available in the environment. You can restore features by explicitly 
loading extensions through settings in the TOOLS.INI file. For example: 


LOAD: C:\BC7\BIN\PWBBASIC.MXT;C:\BC7\BIN\PWBUTILS.MXT 
These lines explicitly load the BASIC and utilities PWB extensions when you edit a file with 


the .BAS or .BI filename extension. If these lines exist in your TOOLS.INI file and you start 
PWB with the following command line, only the BASIC functions are available: 


1E mis roer ed 


cr Wo wit €stl.Das 


The following table lists the filenames of the PWB extensions and describes the functions they 


provide: 
Real-mode file Protected-mode file Provides support for 
PWBBASIC.MXT PWBBASIC.PXT BASIC Compiler functions. _ 
PWBROWSE.MXT PWBROWSE.PXT Source Browser functions. 
PWBC.MXT PWBC.PXT C Compiler functions. This file is 
included on the BASIC distribution 
disks, but is not installed by Setup. 
PWBHELP.MXT PWBHELP.PXT Online Help functions. 
PWBUTILS.MXT PWBUTILS.PXT LINK, NMAKE, CodeView, and 


build functions. 


Controlling the Environment 


The full syntax for starting PWB from the command line is as follows: 


PWB [options] [[programname] [|programname ] ... 


Unlike QBX, programname must include its filename extension if one exists. If you specify 
more than one programname, the first name you specify is the first file PWB edits. The 
remaining files are loaded if you select choose Next from the File menu. 


Option Action 


/e string Executes the PWB commands specitied in 
string when PWB starts up. 

/t file Indicates that the specified fi/e is temporary and 
should not be kept in file history. You must 
precede the name of each temporary file 
with a /t. 
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/PIF file | LIP file] 


/r 


/m position 


ft 
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Prevents PWB initialization files from being 
read at startup. The /DA option prevents 
extensions from being loaded automatically. 
The /DS option prevents the CURRENT.STS 
file from being read. The /DT option prevents 
the TOOLS.INI file from being read. The /D is 
equivalent to /DAST. 

Loads a program list. The /PF option loads the 
NMAKE .MAK file specified by fi/e. The /PL 
option loads the last .MAK file used in PWB. 
The /PP option loads the PWB .MAK file 
specified by file. 

Specifies that all files opened are read-only. 


Puts the cursor at the file location specified by 
position. For example: 


pwr / +> Fag 1 
rPWe /T 5D 


The preceding command line loads the file 
BOOKLOOK.BAS and places the cursor at line 
120, character position 50. 


Lists the command-line options for running 
PWB. 
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The Microsoft Code View debugger helps you locate, identify, and resolve bugs in programs 
under DOS or OS/2. Code View can help you debug programs compiled from within QBX or 
PWB, or from the command line. CodeView can be accessed directly from the Programmer’ s 
WorkBench (PWB). Together, PWB and Code View provide a complete development system 
for mixed-language and OS/2 program development. 


This chapter describes: 


Preparing your programs for debugging with Code View. 
Running CodeView. 

Debugging a program. 

Controlling the flow of execution while debugging. 
Displaying and changing variables. 

Advanced Code View debugging techniques. 
Customizing Code View using the TOOLS.INI file. 


Controlling Code View with command-line options. 


Preparing BASIC Files for CodeView 


CodeView can debug programs created with any editor or environment. QBX and PWB 
provide Code View options for compiling within the environment. With QBX, however. you 
must save your source file in text format before compiling with the Code View option. Source 
files saved in QBX binary format are not compatible with Code View. 
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Programming Style 

To make it easier to debug programs in Code View, you should avoid the following 
programming practices: 

a Using the colon (:) to place multiple BASIC statements on a single line. 


Code View can step through a program one line ata time. If more than one statement occurs 
on a line, Code View treats the line as a single statement. 


w Placing executable statements in include files. 


You cannot trace through executable statements that occur in an include file. Placing 
executable statements in include files is not a good programming practice. 


mw Using non-unique array names. 
Arrays should be named uniquely. If a variable has the same name as an array in your 
program, CodeView assumes that symbol is a variable, not an array. You will not be able to 
perform some operations on that array from the Code View Command window. 


Compiling and Linking 

To debug a program in Code View, you must compile the program with the /Zi or /Zd options 
and link using the /CO option. The /Zi option makes the executable file larger. You can reduce 
the size of programs by compiling with /Zd. You will not be able to view symbols in the Local 
window within CodeView, however. 

You should not use the optimize (/Ot) option when compiling a program for use with 
CodeView. Although Code View can debug an executable file compiled with /Ot, you will not 
be able to pause program execution on lines containing SUB, FUNCTION, or DEF FN 
Statements. 

Object files compiled for use with CodeView must be linked using the /CO option. When 
linking in DOS, you cannot use the /EXEPACK and /CO together. If your program needs to be 
packed to fit in memory, use the CVPACK utility to compress the executable file for 
debugging. 


The syntax tor CVPACK 1s: 
CVPACK ||/HELP | /P]] filename 


If you specify the /P option, CVPACK rewrites the file as compactly as possible. If you don’t 
specify the /P, CVPACK rewrites the file as quickly as possible. In either case, the program 
takes up the same amount of memory. 
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Running CodeView 


To start Code View from the command line, use the CV real-mode or CVP protected-mode 
command and specify an executable file. For example: 


CV 'TEST.. BXE 


To start CodeView from PWB in real or protected mode, choose Debug from the Run menu. By 
default, Code View displays three windows, as shown in Figure 5.1. 


Source Window 


File Edit View Search Run Watch Options Calls Help ) 


SSS ee ae | | 
Local Window 
I] sourcei CS:IP BOOKLOOK.bas (ACTIVE) It 
4: ‘ 
5: 
| 6: DEFINT A-Z 
ie "SINCLUDE: ’ BOOKLOOK.BI’ 
| 8: SCREEN @ 
9: CLS ’ TempRec is for editing and adding record 
8: DIM TempRec AS RecStruct ’ Used only to blank out a TempRec 
1: DIM EmptyRec AS RecStruct ’ See BOOKLOOK.BI for declaration of 
2: DIM BigRec AS RecStruct ’ this structure and its elements 
3: DIM Marker(25) AS INTEGER ' Array to hold SAVEPOINT returns 
4: 
| S: ’ Open the database and the BookStock, CardHolders, and BooksOut table 
Il 00 ee nee eee eee | | 
> t 
i Command Winda, 
<F8=Trace> <Fi8=Step> <F5=Go> <F6=Window> <F3=Display> 


Figure 5.1 The CodeView Debugger 


The “Local window” displays the current symbols along with their addresses, types. and values. 
This window is empty until you begin executing your program. 


The “Source window” displays the program's source code. Since the program loaded in 
CodeView is a compiled executable program, you cannot make changes to the source trom 
within Code View. The Source window shows you where you are in a program and lets you 
execute the program statement-by-statement. 


The “Command window” lets you enter Code View commands and display and evaluate BASIC 
expressions. Although you cannot make changes to a program from Code View, you can use the 
Command window to change the value of variables, write data to memory, and pertorm a 
variety of other tasks. Code View supports a limited number of BASIC intrinsic functions which 
can be called from the Command window. See the Code View online Help on BASIC intrinsic 
functions for more information. 
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important’ CodeView includes extensive online Help. If you request Help and get an error message 
indicating that no Help files were open or that they could not be found, check your 
HELPFILES environment variable. HELPFILES can be set by running NEW-VARS.BAT 
(DOS) or NEW-VARS.CMD (OS/2) from the command line before starting Code View. 
Setting HELPFILES in the PWB environment has no effect in CodeView. 


Within CodeView, environment tasks can be performed by using either the mouse or the 
keyboard. The following table lists commonly used key combinations by category and task. 
The Command window equivalent is given where one exists. (See the online Help on 

Code View commands for a complete list and description of CodeView commands. ) 


CodeView 
Category Task Key sequence command 
Execute Run FS G : 
Step single statement F8 ys 
Procedure step F10 F 
Debug Set watch | Ctrl+W ae oe 
Delete watch Ctrl+U — 
Quick watch Shift+F9 expression 
Set/clear breakpoint F9 BP/BC 
Edit Select text Shift+-direction key — 
Copy Ctrl+Ins = 
Paste Shift+Ins — 
Undo Alt+Backspace — 
Windows Next window : F6 7 —_ 
Previous window Shift+F6 — 
Resize a window Ctrl+F8 — 
Maximize a window Ctrl+F10 — 
Help Get Help on a topic — Fl H 
View table of contents Shift+F — 
Exit Help Esc — 
Redisplay last Help Alt+F 1 — 
Note The Edit tasks are used to copy and paste expressions, values, and blocks of memory. You 


cannot Paste into the Source window. 
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Debugging Your Program 


Important 


Code View is similar to QuickKBASIC Extended (QBX) in that you can watch the value of 
variables while you execute parts of your program. Like QBX, you can execute one line at a 
time, one procedure at a time, or up to a specific location. Unlike QBX, you cannot rewrite 
your program within CodeView. 


Code View also lets you directly manipulate the values stored in variables and in memory. 


Running Your Program 


To execute a single line of code, press F8. 

To execute a line of code or without tracing into procedures, press F10. 
To quickly execute up to a specific location in a program: 

1. Inthe Source window, scroll to the location at which to stop. 


2. Click the right mouse button at that location. 
Code View executes up to that location at normal execution speed. 


To run a program one line at a time: 


1. From the Run menu, choose Animate. 
CodeView immediately begins executing the program. 


2. Press any key to stop. 


When you run your BASIC program in CodeView under DOS, you will not be able to use the 
DOS Shell command from the File menu. This is because BASIC reserves all remaining 
conventional memory while the program is running. To be able to use the DOS Shell command 
you should terminate or restart your BASIC program. 


Viewing Current Data 


When you Start executing a program in Code View, the debugger automatically displays all 
current variables in the Local window. The Local window shows the address, data type. name. 
and value of each variable in the current procedure. For example: 


2FCE:0062 STRING FULLNAMES = "Dan Webb" 

The value 2FCE:0062 is the address of the variable in memory, STRING is the data type. 
FULLNAMES$ is the variable name, and “Dan Webb” is the current value of the variable. 
For arrays and user-defined data types, Code View displays a summary line. For example: 


+2FCE:Q0070 INTEGER AZs [array] = ?CANNOT DISPLAY‘ 
t2FCE:;004a type TESTRECOR FILEBUFFER tesal 
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The plus sign (+) to the left of the memory address shows that there is more information. To see 
the elements in the structure TESTRECOR, select the TESTRECOR line. The line expands as 


follows: 


The minus sign (-) to the left of the memory address shows that the line is fully expanded. 


You cannot expand BASIC arrays. Instead, you must set watches on elements in the array to 
see their values. 


Using Watches 


Watches let you observe the value of a variable or expression as your program executes. Since 
Code View displays the value of local variables in the Local window, Code View's watches are 
mainly useful when the Local window is not displayed or for observing array elements and 
expressions. 


To add a variable to the Watch window: 


1. Place the cursor on the variable and press Ctrl+W. 
Code View displays the Add Watch dialog box. 


Choose OK. 
Code View adds the variable to the Watch window, as shown in Figure 5.2. 


he 


File Edit View Search Run Watch Options Calls Help 

I-| local | watch} 
466) :64AC INTEGER ANYRECORDSy = |]+BigRec = {...} 
406D:64A6 INTEGER ADDED’. = @ answers = 6 
480) :4496 STRING ALERTS = "" PendingFlag = 8 | Watch Window 
468D:648C INTEGER ARGUMENTy = 6 
486): 846A INTEGER ANSWER = @ 

Source! CS:1P BOOKLOOK. bas OCT | | 

t 


STACK 4066 ’ Set large stack for recursioff 
’ also resets FRE(-2) to stack 


answer% = Get Inputz(BigRec) ’ Find out what the user wants 


IF answer < UNDO THEN ’ Excludes UNDOALL & INVALIDKE 
CALL EditCheck(PendingFlag, answer, BigRec) 
END IF 


Il 
: a 
va 
3: 
4: 
Si 
6: 
te 
8: 
9: 


<F8=Trace> <F18=Step> <F5=Go> <F6=Window> <F3=Display> 


Figure 5.2 CodeView Watch Window 
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A variable may be followed by the message “Watch Expression Not in Context.” This message 
appears when program execution has not yet reached the statement in which the variable is 
defined. Global variables, which can be watched from anywhere in the program, never cause 
Code View to display this message. 


To remove a variable from the Watch window, place the cursor on any line in the Watch 
window and press Ctrl+Y to delete the line. 


You can place as many variables as you like in the Watch window; the quantity is limited only 
by available memory. Code View automatically updates all watched variables as the program 
runs. This can slow execution speed considerably. 


Displaying Expressions in the Watch Window 


The Add Watch dialog box prompts for an expression, not simply a variable name. As this 
suggests, you can enter an expression (that is, any valid combination of variables. constants. 
and operators) for Code View to evaluate and display. 

You are not limited to evaluating BASIC expressions. The Language command trom the 
Options menu offers a choice of BASIC, C, or FORTRAN evaluation for al] expressions. The 
ability to select the language evaluator is especially useful when debugging mixed-language 
programs. 

By reducing several variables to a single, easily read value, an expression can be easier to 
interpret than the components that comprise it. 


Displaying Array Elements Dynamically 


You can display a single element of an array using a specific subscript. You can also specity a 
variable array element, which changes as some other variable changes. For example. suppose 
that the loop variable p is a subscript for the array CatalogPriceé@. The Watch window 
expression CatalogPrice@(p) displays only the array element currently specitied by 

not the entire array. 

You can mix constant and variable subscripts. For example, the expression 
BigArray+(3,1i) displays the element in the third row of the array to which the index 
variable i points. 


Using Quick Watch 


A quick watch shows the current value of a variable. This is useful for quickly finding the value 
of a variable at some point in the program without adding it to the Watch window. 


To display a quick watch: 
1. Place the cursor on the variable to watch. 


2. From the Watch menu, choose Quick Watch (or press Shift+F9). 
Code View displays the Quick Watch dialog box with the value of the variable. 
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The Quick Watch display automatically expands user-defined types to their first level. You can 
expand or contract an element justas you would in the Watch window by placing the cursor on 
the appropriate line and pressing Enter. 


Displaying Memory 


You can view data at specific memory addresses using Code View. 


To display memory, choose Memory from the View menu. Code View displays the Memory 
window, as shown in Figure 5.3. 


File Edit View Search Run Watch 2) i — Calls 
0 — —_——-uatch_—______1 
466D:04AC INTEGER ANYRECORDS. = |}+BigRec 
400D:84A6 INTEGER ADDED, = 8 answery = @ 
400) :8496 STRING ALERTS = "" Pend ligt lag = = 6 
466D:848C INTEGER ARGUMENT = @ 

ourcel CS: IP BOOKLOOK.bas (ACTIVE) 


IF answer < UNDO THEN " Excludes UNDOALL & omits 
CALL EditCheck(PendingFlag, answer, BigRec) 
END IF 


|_ enory! byte DS:0000 (ACTIVE) nn (1/0 
| 2655 :888@ CD 28 BD SA 88 9A FO FE 1D F@ 8B 62 19 25 51 3. .P.........40. 
655:0018 19 25 BB GA 19 25 AZ 16 81 81 O1 OO O2 G3 FF FF W%...%.....0 000s 
655:0026 FF FF FF FF FF FF FF FF FF FF FF FF @4 17 A2 22 
655:8838 EB 22 14 86 18 64 55 26 FF FF FF FF 68 60 88 @@ . — Memory Window 
65506468 66 86 68 66 88 46 66 48 OA 86 86 40 46 48 48 48 : 
655:6058 CD 21 CB 04 88 88 80 88 88 48 G0 G2 GO 20 20 20 


., Sees <F18=Step> <F5=Go> <F6=Window> <F3=Display> <Sh+F3=Memory Format> 


Figure 5.3 CodeView Memory Window 


Up to two Memory windows can be open at once. 


By default, memory is displayed as hexadecimal byte values, with 16 bytes per line. At the end 
of each line is a second display of the same memory in ASCII form. Values that correspond to 
printable ASCII characters (decimal 32 through 127) are displayed in that form. Values outside 
this range are shown as periods. 
Byte values are not always the most convenient way to view memory. If the area of memory 
you're examining contains character strings or floating-point values, you might prefer to view 
them in a directly readable form. 
To change the way data is displayed in the current Memory window: 
1. From the Options menu, choose Memory Window. 

Code View displays the Memory Window Options dialog box. 


2. Select the format for display, and choose OK. 
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You can also directly cycle through these display formats by pressing F3. 


If a section of memory cannot be displayed as a valid floating-point number, the number shown 
includes the characters NAN (not a number). 


Displaying the Processor Registers 


To view processor registers, choose Register from the View menu. Code View opens a window 
on the right side of the screen, as shown in Figure 5.4. The current values of the 
microprocessor’s registers appear in this window. 


Register Window 


File Edit View Search Run Watch Options Calls 
* local 

406D :@4AC INTEGER 

460D:84A6 INTEGER ADDEDy =|] ansuerz% = @ 

466) :6496 STRING ALERTS =|] PendingFlag = @ 

488D:848C INTEGER ARGUMENT} 


IF answer < UNDO THEN ’ Excludes UNDOALL| 
CALL EditCheck(PendingFlag, answer, BigRec) 
END IF 


CD 26 6D 5S@ 66 9A FA FE 1D FO 8B @2 19 25 51 83. .P.. 
19 25 BB @A 19 25 HZ 16 61 O1 81 6 O2 3 FF FF .x...¥ 
FF FF FF FF FF FF FF FF OFF FF OFF OFF 64.1? A222 occu 
EB 22 14 86 18 66 5S 26 FF FF FF FF 80 86 60 80 .”.... 
66 66 88 60 86 66 86 66 48 86 OB 40 OO 86 00 40 


enory1 byte DS:8800 Lee] 
t 


> 


<F8=Trace> <Fi8=Step> <F5=Go> <F6=Window> <F3=Display> <Sh+F3=Memory Format> 


Figure 5.4 CodeView Register Window 


At the bottom of the window is a group of mnemonics representing the processor flags. When 
you first open the Register window, all values are shown in normal-intensity video. Any 
subsequent changes are marked in high-intensity video. For example, suppose the overflow flag 
is not set when the Register window is first opened. The corresponding mnemonic is NV and 
appears in light gray. If the overflow flag is subsequently set, the mnemonic changes to OV and 
appears in bright white. 


Choosing the 386 Instructions command (DOS only) from the Options menu displays the 
registers as 32-bit values if your computer uses an 80386 processor. Selecting this command a 
second time reverts to a 16-bit display. This command is not available in protected mode: the 
registers are shown in 16-bit display only. 


You can also display the registers of an 8087/287/387 coprocessor in a separate window by 
choosing the 8087 command from the View menu. If your program uses the coprocessor 
emulator, the emulated registers are displayed instead. 
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Modifying the Values of Variables, 
Registers, and Memory 


You can easily change the values of numeric variables, registers, or memory locations 
displayed in the Watch, Local, Memory, Register, or 8087 window. Simply place the cursor at 
the value you want to change and edit it to the appropriate value. To undo the last change you 
made, press Alt+Backspace. You cannot directly change the value of string variables. 


The starting address of each line of memory displayed is shown at the left of the Memory 
window, in segmentiaddress form. Altering the address automatically shifts the display to the 
corresponding section of memory. If that section is not used by your program, memory 
locations are displayed as double question marks (??). 

When you select Byte display from the Memory Window Options dialog box, Code View 
presents both a hexadecimal and an ASCII representation of the data in memory. (Byte display 
is the default.) You can change data in memory either by entering new hex values over the 
hexadecimal representation of your data or by entering character values over the character 
representation. 

To toggle a processor flag, click left on its mnemonic. You can also place the cursor on a 
mnemonic, then press any key (except Tab or Spacebar). Repeat to restore the flag to its 
previous setting. 

The effect of changing a register, flag, or memory location may vary from no effect at all to 
crashing the operating system. You should be cautious when altering machine-level values; 
most of the items you would want to change can be altered from the Local or Watch window. 
Direct manipulation of register values can be valuable, however, when you are debugging a 
BASIC program that calls assembly language routines. You can change register values to test 
assumptions before making changes in your source code and recompiling. 


Setting Breakpoints 


You can skip over the parts of the program that you don’t want to examine by specifying one or 
more lines as breakpoints. When you start the program by pressing F5, the program executes at 
full speed up to the first breakpoint, then pauses. Pressing F5 continues program execution up 
to the next breakpoint, and so on. 

You can set as many breakpoints as you like (limited only by available memory). There are two 
ways to set breakpoints: 


a Double-click anywhere on the desired breakpoint line. The selected line is highlighted to 
show that it is a breakpoint. (Code View highlights lines that have been selected as 
breakpoints.) To remove the breakpoint, double-click on the line a second time. 


a Place the cursor anywhere on the line at which you want execution to pause. Press F9 to 
select the line as a breakpoint. Press F9 a second time to remove the breakpoint. 


A breakpoint line must be a program line that represents executable code. You cannot select a 
blank line, a comment line, or a declaration line (such as a variable declaration) as a breakpoint. 
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Note 


A breakpoint can also be set at a function or an explicit address. To set a breakpoint at a 
function, enter its name in the Set Breakpoint dialog box. To set a breakpoint at an address, 
enter the address in segment:offset form. 


Once execution has paused, you can continue execution by pressing F5. 


Setting Conditional Breakpoints 


Using CodeView 


Code View lets you set conditional statements that stop execution when an expression becomes 


true or changes value. (QBX refers to these conditional breakpoints as “watchpoints.”) 
To set a conditional breakpoint: 


1. From the Watch menu, choose Set Breakpoint. 
Code View displays the Set Breakpoint dialog box, as shown in Figure 5.5. 


2. Select one of the conditional break options from the dialog box, such as Break When 
Expression is True. 
If you select one of the Break at Location options, Code View takes you to the line number 
displayed in the Location field when the breakpoint is reached. If you select one of the 
other two options, Code View takes you to the last statement that was executed. 


3. Choose OK. 


Set Breakpoint 


Break at Location. 
reak at Location if Expression is True. 


reak When Expression is True. 
reak When Expression has Changed. 


( 
( 
( 
( 
( 


) 

»B 

) Break at Location if Expression has Changed. 
8B 

)B 


Location: [.78 


Expression: [N/A 


Pass Count: [ Length: [N/A 


Commands: [ 


< OK > <Cancel> < Help > 


Figure 5.5 CodeView Set Breakpoint Dialog Box 


When a breakpoint is tied to a variable, Code View must check the variable’s value after each 
machine instruction is executed. This slows execution greatly. For maximum speed when 
debugging, either tie conditional breakpoints to specific lines, or set conditional breakpoints 
only after you have reached the section of code that needs to be debugged. 
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Code View can automatically create a history file with all the debugging instructions and input 
data you entered when testing a program. This history file is used to replay the debug session to 
a specific point. 

To record a debug session, choose History On from the Run menu. 

To stop recording. choose History On a second time. 


Recordings can be used to keep track of debugging. You can quit after a long debugging 
session, then pick up the session later in the same place. 


The principal use of recording a debug session is to allow you to back up when you make an 
error or Overshoot the section of code with the bug. For example, you may have to execute a 
function manually many times before its bug appears. If you then enter a command that alters 
the machine's or program’s status and thereby lose the information you need to find the cause 
of the bug, you have to restart the program and manually repeat every debugging step to return 
to that point. Even worse, if you don’t remember the exact sequence of events that exposed the 
bug, it could take hours to find your way back. 


Recording your session eliminates this problem. Choosing Undo from the Run menu 
automatically restarts the program and rapidly executes every debug command up to (but not 
including) the last one you entered. You can repeat this process as many times as you like until 
you return to the desired point in execution. 

To add steps to an existing recorded session, choose History On, then select Replay. When 
replay has completed, perform whatever new debugging steps you want, then select History On 
a second time to terminate recording. The new tape contains both the original and the added 
commands. 


Code View records only those mouse commands that apply to Code View. Mouse commands 
recognized by the application being debugged are not recorded. 


Replay Limitations Under 0S/2 


There are some limitations to dynamic replay when debugging under OS/2: 


a The program must not respond to asynchronous events. (Replay under OS/2 Presentation 
Manager is not currently supported because it violates this restriction.) 


a Breakpoints must be specified at specific source lines or for specitic symbols (rather than 
by absolute addresses), or replay may fail. 


a Single-thread programs behave normally during replay. However, one of the threads ina 
multithread program may cause an asynchronous event, violating the first restriction. 
Multithread programs are, therefore, more likely to fail during replay. 


a Multiprocess replay will fail. Each new process invokes a new Code View session. The 
existence of multiple sessions makes it impractical to record the sequence of events if you 
execute commands in a session other than the original. 
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Advanced CodeView Techniques 


Once you are comfortable displaying and changing variables, stepping through the program, 
and using dynamic replay, you may want to experiment with advanced techniques. 


Setting Command-Line Arguments 


If your program retrieves command-line arguments, you can specify them with the Set Runtime 
Arguments command from the Run menu. Enter the arguments in the Command Line field 
before you begin execution. (Arguments entered after execution begins cause an automatic 
restart. ) 


Multiple Source Windows 


You can open two Source windows simultaneously. The windows can display two different 
sections of the same program, or one can show the high-level listing and the other the assembly 
language listing. In the latter case, the contents of the windows are synchronized. The next 
assembly language instruction to be executed matches the next line of source code. 

You can move freely between these windows, executing a single line of source code or a single 
assembly instruction at a time. 


Using Breakpoints Efficiently 


Breakpoints slow execution when debugging. You can increase Code View's speed by using the 
/R command-line switch if you have an 80386-based computer. This switch enables the 386°s 
four debug registers, which support breakpoint checking in hardware rather than in software. 


Printing Selected ltems 


To print all or part of the contents of any window: 


1. From the File menu, choose Print. 
Code View displays the Print dialog box. 


2. Select the information to print and whether to append the information to an existing file or 
to overwrite the file. 
By default, print output is to the file CODEVIEW.LST in the current directory. If you want 
the output to go to a printer, enter the appropriate device name (such as LPT 1: or COM2:) 
in the To File Name field. 


3. Choose OK. 


Handling Register Variables 


A register variable is stored in one of the microprocessor’s registers, rather than in RAM. This 
speeds access to the variable. 
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A conventional variable can become a register variable when the compiler stores an often-used 
variable, such as a loop variable, in a register to speed execution. 

Register variables can cause problems during debugging. As with local variables, they are only 
visible within the function where they are defined. In addition, a register variable may not 
always be displayed with its current value. 


Redirecting CodeView Input and Output 


The Command window accepts DOS-like commands that redirect input and output. These 
commands can also be included on the command line that invokes Code View. Whatever 
follows the /C option on the command line is treated as a Code View command to be 
immediately executed at startup. For example: 


“te + ~ ile mvorot 
File; >outfile myprog 


This command line redirects input to. infile, which can contain startup commands for 
CodeView. When Code View exhausts all commands in the input file, focus automatically shifts 
to the Command window, Output is sent to out file and echoed to the Command window. 
The © must precede the > command for output to be sent to the Command window. 


Redirection is a useful way to automate Code View startup. It also lets you keep a viewable 
record of command-line input and output, a feature not available with dynamic replay. (No 
record is kept of mouse operations.) Some applications (particularly interactive ones) may need 
modification to allow for redirection of input to the application itself. 


Customizing CodeView with the TOOLS.INI File 
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The TOOLS.INI file customizes the behavior and user interface of several Microsoft products. 
You should place it in a directory pointed to the INIT environment variable. (If you do not use 
the INIT environment variable, Code View looks for TOOLS.INI only in its source directory.) 


The Code View section of TOOLS.INI is preceded by the following line: 


If you are running the protected-mode version of CodeView, use [cvp] instead. If you run both 
versions, include both: [cv cvp]. 


Most of the TOOLS.INI customizations control screen colors, but you can also specify options, 
such as startup commands or the name of the file receiving Code View output. Online Help 
contains full information about all TOOLS.INI switches for Code View. 
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Controlling CodeView with Command-Line Options 


The following options can be added to the command line that invokes Code View: 


Option 
2 


/Ccommands 


/D{ buffersize]] 


KE 
/F 


[O11] 


/K 


/Ldlls 
/M 


/NUO' 1] 


/O 


Effect 


Two-monitor debugging. One display shows the output of the 
application; the other shows Code View. 


Display in 25-line mode. 

Display in 43-line mode. (EGA or VGA only) 

Display in 50-line mode. (VGA only) 

Display in black and white. 

All items following this switch are treated as Code View commands 


to be executed immediately upon startup. Commands must be 
separated with a semicolon (;). 


Use disk overlays, where buffersize is the decimal size of the 
overlay buffer, in kilobytes. The acceptable range is 16K to 125K. 
with the default size 64K. (DOS only) 


Use expanded memory for symbolic information. (DOS only ) 


Flip screen video pages. When your application does not use 
graphics, up to eight video screen pages are available. Switching 
from Code View to the output screen is accomplished more quickly 
than swapping (/S) by directly selecting the appropriate video page. 
Cannot be used with /S. (DOS only) 


[IO enables nonmaskable-interrupt and 8259-interrupt trapping. 
This enables Ctrl+C and Ctrl+Break for PCs that Code View does 
not recognize as IBM-compatible. /l or /I] turns off interrupt 
trapping. (DOS only) 


Use this option if you encounter a deadlock situation because the 
keyboard buffer is full when you restart the program you are 
debugging, exit Code View before your program finishes execution, 
or debug an application that does not accept keystrokes. 


Load DLLs specified. DLLs must be separated by a semicolon (:). 
(OS/2 only) 

Disable the mouse for Code View. Does not affect the use of the 
mouse in the application being debugged. 

/NO enables nonmaskable-interrupt trapping. This enables Ctrl+C 
and Ctrl+Break tor PCs that CodeView does not recognize as 
IBM-compatible. /N or /N1 turns off interrupt trapping. 

(DOS only) 


Debug child processes (offspring). (OS/2 only) 
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/R Use 386 hardware debug registers. (DOS only) 


IS Swap screen in buffers. When your program uses graphics, all 
eight screen buffers must be used. Switching from Code View to 
the output screen is accomplished by saving the previous screen in 
a buffer. Cannot be used with /F. (DOS only) 


[X Use extended memory for symbolic information. (DOS only) 
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The Microsoft Advisor online Help system is more than a learning tool—it’s a reference 
database designed especially for professional programmers. Help gives you instant reference 
information about the BASIC language, development environments, compiler options, utilities. 
and error messages. You can also copy sample code from a Help screen and paste it directly 
into your BASIC source file. Using the Microsoft Help File Creation utility (HELPMAKE). 
you can even create your own Help files. 


This chapter describes: 

a Installing Help. 

= Organization of Help. 

sw Navigating in Help. 

= Copying and pasting Help information. 
ws Creating your own Help files. 


w Using QuickHelp. 


Installing Help 


Use the Setup program to install Help. In the Specify Files to Install menu, turn on the Help 
Files for Chosen Tools check box. Setup includes all the Help files you need when it installs 
Microsoft BASIC. 


At this point, you can use online Help in the QuickKBASIC Extended (QBX) environment. To 
use Help in the Programmer’s WorkBench (PWB), Code View, and QuickHelp environments. 
you must specify where each of these applications should look for their Help files by setting the 
HELPFILES environment variable. HELPFILES can be set in several different places. PWB. 
Code View, and QuickHelp search the following locations in the order shown and use the first 
HELPFILES setting they find: 


1. Environment selection from the PWB Options menu. (This only has an effect in PWB.) 
2. TOOLS.INI file. 
3. AUTOEXEC.BAT file (DOS) or CONFIG.SYS file (OS/2). 


If HELPFILES is not set in one of these locations, PWB and QuickHelp will search for help 
files in the current directory and in the directories listed in the PATH environment variable. 
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You can set HELPFILES and other environment variables for a session by running the 
NEW-VARS.BAT (DOS) or NEW-VARS.CMD (OS/2) file from the command line. You may 
want to incorporate the settings in these files into your AUTOEXEC.BAT (DOS) or 
CONFIG.SYS (OS/2) tiles. For information on how to do this, see the section “After Running 
Setup” in Chapter 2. 


Help Topics and Hyperlinks 
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Online Help is organized as a set of topics. Instead of thumbing through a manual, you can 
move from one topic to another related topic by using links (or cross-references). Help 
remembers the last 20 screens you've viewed, so you can retrace your path at any time. 


Explicit Cross-References 


Explicit cross-references, called “hyperlinks,” are tied to a word or phrase at a specific location 
in Help. You simply select a hyperlink, using the mouse or keyboard, to move to a new screen 
of related information. 


Special characters set off hyperlink buttons. Figure 6.1 shows examples. 


HELP: DO...LOOP Statement it 
4Suntaxe <4Detailsh <4Example> 4Contentsk <4Indexb <Back? | — 


DO C{WHILE | UNTIL} condition] 
[statementb lock] 
(EXIT DOJ 
[statenentblock] 
LOOP | 


condition A numeric expression that BASIC evaluates as true Hyperlink 
(nonzero) or false (zero). Buttons 
EXIT DO fn alternative exit from a DO...LOOP. Transfers 
control to the statement following LOOP. 


The program lines between the DO and LOOP statements are repeated 
while a condition is true or until a condition becomes true. 
See Details for alternate syntax. 


See Also 4WHILE...WEND> = «FOR. . .NEXT —— — - —}j— 
Figure 6.1 Help Screen with Hyperlinks 


To move forward between hyperlinks, press the Tab key; Shitt+Tab moves you backward. You 
can also type the first letter of a hyperlink to move to that hyperlink. 


Implicit Cross-References 


All BASIC keywords (functions, statements, operators, and metacommands) are implicit cross- 
references. Implicit cross-references have no special formatting. For example, the word “open” 
provides context-sensitive help on the OPEN statement wherever it appears, whether in your 
programs or in a Help screen. To use an implicit cross-reference, place the cursor on or 
immediately following the keyword, and then press FI or click the right mouse button. 
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Help Categories 


There are five categories of help: 

sw Using Help 

= Keyword and symbol Help 

a Topic-based Help 

= Programming environment Help 


ws Error message Help 


Using Help 


You can get information about the online Help system itself at any time by choosing the Using 
Help command from the Help menu. The Using Help screen provides a quick overview of the 
Help system and gives instructions for accessing Help with the keyboard or mouse. 


Keyword and Symbol Help 


Online Help provides context-sensitive help for BASIC keywords and for symbols in your 
program, such as procedures and variables. 


Keyword Help 


Keywords include functions, statements, operators, and metacommands. Every keyword in 
Microsoft BASIC is an implicit cross-reference. To get information on any BASIC keyword (in 
your program or within the online Help system), place the cursor on the keyword, and press F | 
or click the right mouse button. For example, type do in the QBX View window, and then 
press Fl. The Syntax screen for the DO...LOOP statement appears, as shown in Figure 6.2. 


HELP: DO...LOOP Statement ——————_——|j 
“Syntax <Details> <Example> 4Contentsh <Index> <Back 


DO ({WHILE | UNTIL} condition] 
[statementblock] 

(EXIT DO) 
[statementb lock] 

LOOP 


® condition A numeric expression that BASIC evaluates as true 
(nonzero) or false (zero). 

s EXIT DO An alternative exit from a DO...LOOP. Transfers 
control to the statement following LOOP. 


= The program lines between the DO and LOOP statements are repeated 
while a condition is true or until a condition becomes true. 
® See Details for alternate syntax. 


See Also WHILE. . .WEND> “FOR. . .NEXT 


Figure 6.2 BASIC Syntax Help Screen 
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If you want to see a programming example using the DO...LOOP statement, move to the Help 
window, then choose the Example hyperlink. If you need additional information, choose the 
Details hyperlink. 

You can browse the complete list of BASIC keywords by choosing the Keywords by Task 
hyperlink from the BASIC Help Table of Contents screen. 


Symbol Help 


To get information on any symbol in your program from QBX, position the cursor anywhere on 
the symbol and then press F1 or click the right mouse button. The Help system will identify the 
symbol (variable, function, etc.) and where it is used in your program. This type of Help is only 
available in QBX. 


To view symbol information in PWB, you must use the Source Browser. For instructions on 
using the Source Browser, see Chapter 4, “Using PWB.” 


Topic-Based Help 


You can use the Help system to get an overview of available topics when you have a general 
idea of the information you need. For example, suppose you want to learn about QBX°s 
customizable keystrokes, but you don’t know where to look. Choose the Contents hyperlink in 
any Help window, or choose Contents from the Help menu. The BASIC Help Table of 
Contents screen appears, as shown in Figure 6.3. 


HELP: Table of Contents ———————————_- 
“Copyright Product Support> *4Contentsh <4Index> <Back> 


rientat ion uick Reference 
4Using Help» 4QBX Memory and Capacity> 
4Using Menus and Dialogs> 4ASCII Character Codes> 
4Keywords by Task> 4Keyboard Scan Codes> 
4Run-Time Error Codes> 
Language Elements 418 Common Quest ions> 
4BASIC Character Set> 
4BASIC Program Line> Keys 
Wariables, Constants, Data Types> 4Shortcut Keys> 
4Expressions and Operators 4Editing Keys> 
4Modules, Overlays, Procedures> Wiew and Search Keys> 
4Run and Debug Keys> 
ommand-Line Options d4Help Keys 
4QBX Command Line> 4Conf iguring Keys 
4BC Command Line> 


Figure 6.3 BASIC Help Table of Contents Screen 


The BASIC Help Table of Contents screen is broken into five subgroups: Orientation, 
Language Elements, Command-Line Options, Quick Reference, and Keys. 
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Programming Environment Help 


You can get context-sensitive Help on any menu command or dialog box. For example. to learn 
about the Create File command in the QBX File menu: 


1. Open the File menu. 
2. Press the Down direction key to highlight Create File (do not press Enter), and then press 
Fl. The Help screen for the Create File command appears, as shown in Figure 6.4. 


HELP: Create File Command 


Use to begin entering a new file for a multiple-module 
program. This can be 

= A program module 

#8 An include file 

8 A document file 


The new file will become part of the currently loaded 
program. 


Tip: Create File can be used when no program is loaded 
as an alternative to the File menu’s New Program 
command to create a new main program module. 


Figure 6.4 Help on the Programming Environment 


You can also get help about a dialog box. Press F1 or click the Help button to display 
information about the dialog box. 


Error Message Help 


Whenever you encounter an error message, you can press F1 to get help on the cause of the 
error. Most error message Help screens contain suggestions on how to avoid the error. 
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Navigating in the Help System 


The following table summarizes Help keystrokes. 


Press this key To do this 

FI Get Help on the selected item. 

Shitt+F 1 In QBX, get help on using the Help system. In PWB, CodeView, 
and QuickHelp, Shift+F1 displays the Help Table of Contents. 

Alt+F] Display previous Help screen. You can retrace your path through 
the last 20 Help screens. 

Esc Close the Help window. 

PgDn Scroll Help information down when the Help window is active. 

PgUp Scroll Help information up when the Help window is active. 

Tab Move to the next hyperlink in the active Help window. 

Shitt+Tab Move to the previous hyperlink in the active Help window. 


Copying and Pasting Help Information 


You can copy any text that appears in the Help window to another window. To test a sample 
program from the Help window, just copy it to the program window and then choose Start 
(QBX) or Execute (PWB) from the Run menu. 


To copy and paste, follow these steps: 
1. Select the text you want to copy. 
2. Press Ctrl+Ins. 


3. Inthe program window, place the cursor where you want to insert the text, and then press 
Shift+Ins. 


Creating Custom Help Files 


The HELPMAKE utility allows you to create or modify Help files for use with Microsoft 
products. For example, you could write Help text describing a new function you have written 
for a Quick library. You can then display Help information about your function just as you 
would display Microsoft-supplied Help information. 

HELPMAKE translates Help text files into a Help database accessible from the QBX 
programming environment or other Microsoft language products. You can either create Help 
files from scratch, or you can use HELPMAKE to decompress the Microsoft-supplied Help 
database and then modify it. 


For complete information on building your own Help system, see Chapter 22, “Customizing 


Online Help,” in the Programmer's Guide, or select HELPMAKE from the main Help Table of 
Contents in PWB. 
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Using QuickHelp 


Microsoft QuickHelp lets you read Microsoft Advisor Help files without running a 
programming environment. This is useful if you are running Microsoft Windows or OS/2 and 
you want to keep Help information open in a window at all times. QuickHelp is also usetul for 
reading Help databases that you have created for your own applications. 


To start QuickHelp, type: 
QH 


Figure 6.5 shows Microsoft QuickHelp displaying Help on itself. 
File View Categories References Paste Options 


Microsoft QuickHelp 


B - Views previous topic in database HOME - Moves to beginning of topic 
- Searches for duplicate topics Moves to end of topic 

- Continues a search Moves up one screen 

- Goes to string in current topic Moves down one screen 

- Displays this help screen Moves up one line 

- Views history of topics viewed Moves down one line 

- Views last screen Moves to next button 

- Views next topic in database Exits menu or dialog box 
- Searches for topic 

- Displays table of contents 

~ Hides QuickHelp window 

- Exits QuickHelp 

- Prints current topic 


D 
E 
G 
H 
I 
L 
N 
$ 
T 
W 
X 


Menus may be chosen by pressing the first letter of the menu (with or 
without a CTRL or ALT key). You can get help on a menu item by pressing the 
Fi key while the menu item is highlighted, or by pressing the right mouse 


button. n 
Microsoft QuickHelp ——@&— —————— 


Figure 6.5 QuickHelp 


QuickHelp searches for Help files in the paths and the order described in the section “Installing 
Help” earlier in this chapter. In addition, QuickHelp also uses the QH environment variable to 
define additional directories to search. For example: 

SET HELPFILES=C:\BC7\HELP 

SET QH=C:\LANMAN\HELP 


If these lines are entered from the command line, QuickHelp will search in CABC7\HELP and 
CALANMANMUHELP for Help files. PWB and Code View, however, will not search in 
CALANMANMHELP unless it is included in the HELPFILES environment variable. 
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This chapter explains how to increase the amount of memory available under DOS to help you 
create the largest possible running applications using each of the Microsoft BASIC 
environments. It shows you how to take advantage of extended and expanded memory by using 
one or more of the three device drivers included in the package: HIMEM.SYS. 
SMARTDRV.SYS, or RAMDRIVE.SYS. 


Overview 


You can use a variety of techniques to make more memory available for program use. such as: 


= Removing all unnecessary memory-resident programs and device drivers. (Check your 
CONFIG.SYS and AUTOEXEC.BAT files to see what you have installed.) 


a Using extended and/or expanded memory. Extended and expanded memory are available 
through the use of add-on memory boards. Some system boards have extended or expanded 
memory built in as well. Add-on memory boards include extended memory, expanded 
memory, and some boards that can be configured for either. Expanded and extended 
memory are used in different ways: 
= Extended memory. You can use the HIMEM.SYS device driver provided with this 
package or another extended-memory driver. 

= Expanded-memory emulators. Many extended-memory drivers can use some or all 
memory to emulate expanded memory. Information in this chapter about expanded- 
memory hardware applies to expanded-memory emulators as well. 

- Expanded memory. Expanded memory provides up to 1.2 megabytes of buffer space to 
the ISAM portion of a BASIC program. 


You can use extended and expanded memory at the same time. However, only one 


expanded-memory driver and one extended-memory manager can run on the system. Use 
an expanded-memory emulator only if you have no expanded-memory hardware. 
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Using Extended Memory (XMS) 


Extended memory requires an 80286 or later processor. The extended-memory device drivers 
compatible with BASIC observe the Extended Memory Specification (XMS), version 2.0 and 
higher. You can use the HIMEM.SYS device driver provided in this package, or you can use 
your own extended-memory driver if it supports XMS version 2.0 or higher. 


The HIMEM.SYS Device Driver 


The HIMEM.SYS device driver provides a 64K area immediately above one megabyte called 
the High Memory Area (HMA). Only one piece of software can reside in HMA. 


You must have DOS version 3.0 or later to run HIMEM.SYS. To install HIMEM.SYS, place 
the following statement in your CONFIG.SYS file: 


device=|[drive:||[|path]JHIMEM.SYS |/HMAMIN=tsrmin][/NUMHANDLES=/handles ]] 
|/SHADOWSION | OFF]}]] [/MACHINE=machine ]] 


In the preceding syntax, ts7vuin is the minimum size, in kilobytes, that a memory-resident 
program must have to be placed in HMA. The default value of 0 lets any memory-resident 
program request use of this area for extended memory. 

The handles field sets the maximum number of Extended Memory Block handles that 
HIMEM.SYS supports. Each piece of software that you load into extended memory above 
HMA requires an additional handle. The handles field defaults to 32 and must be between 

| and 128. Each additional handle requires 6 bytes of memory. 

The /SHADOW option enables or disables shadow RAM. Some computers make ROM faster 
by “shadowing” itin RAM — that is, copying the ROM code into RAM memory at startup. 
This uses some extended memory. On systems with 384K of extended memory, HIMEM.SYS 
automatically disables shadowing. You can use /SHADOWE=ON to explicitly enable shadowing 
on systems with less than 384K of extended memory. 


The /MACHINE option tells HIMEM.SYS what type of computer you are using. In most cases, 
HIMEM.SYS automatically detects the type of machine you are using. Currently, the only 
system which requires this switch is the Acer 1100. If you are using this system, you should use 
the option /MACHINE:ACER1] 100. 


Other Extended-Memory Device Drivers 


In general, extended-memory device drivers make memory available by using three kinds of 


addresses: 
e@ A 64K area starting at address FFFF:0010, just above conventional memory. 


ea Addresses above this 64K area. This region can be accessed by temporarily switching into 
protected mode, then copying the contents to a lower address. 


w Unused addresses above 640K but below one megabyte. These are areas reserved by the 
system but currently unused. 
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HIMEM.SYS supports the first two kinds of addressing. 


Some extended-memory device drivers can move memory-resident programs into the third 
area—unused addresses below one megabyte. Doing so makes more conventional memory 
available. 

For example, if you have an 80386 processor and the 3836MAX.SYS device driver (from 
Qualitas, Inc.), you may be able to move the ISAM TSR into unused address space. This 
requires a sufficiently large contiguous area of memory and is dependent on your system 
configuration. Install 336MAX.SYS in your CONFIG.SYS file, and then execute the following 
DOS-level commands: 


386MAX loadhigh 
PROISAMD 
386MAX loadlow 


The first command directs the 386MAX driver to load software into high memory (above 
640K). PROISAMD is the full version of the ISAM memory-resident program (database 
creation and access). The third command restores normal loading. 


Using Expanded Memory (EMS) 


Expanded memory is compatible with all 8086-family processors. It is implemented by a 
paging mechanism to swap up to 64K into an 8086-addressable area. The expanded-memor) 
device drivers compatible with BASIC observe the Lotus-Intel-Microsoft (LIM) Expanded 
Memory Specification (EMS). To ensure compatibility with QBX and ISAM, use device 
drivers that support the LIM 4.0 specification. 


To use expanded memory, you must install an expanded-memory device driver in your 
CONFIG.SYS file. Hardware manufacturers supply a device driver with their expanded 
memory board. Two of the device drivers included in this package, RAMDRIVE.SYS and 
SMARTDRV.SYS, can be used with expanded memory. 


Note All of the features described in this section also apply to expanded-memory emulators. 


Using RAMDRIVE 


The RAMDRIVE.SYS device driver lets you use a portion of your computer's memory as an 
additional hard disk. This disk is referred to as a RAM disk or virtual disk and is much faster 
than a physical hard disk. 

You can place a RAM disk in conventional, extended, or expanded memory. On most 
machines, RAMDRIVE.SYS runs fastest with expanded memory. RAMDRIVE.SYS always 
uses some conventional memory. The exact amount depends on your hardware configuration 
and varies between systems. 
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The system reads and writes to the RAM disk almost as fast as to main memory. If you set the 
TMP environment variable to a directory on a RAM disk, a number of programming tools 
(notably LINK and ISAM) will use the RAM disk to hold temporary files, thus speeding up 
operations, You can also copy libraries and frequently used executable files to RAMdrive at the 
beginning of a session to increase speed. Placing source files on the RAM disk is risky since all 
information is deleted from the RAM disk when you reboot. 


To install RAMDRIVE.SYS, include the following command line in your CONFIG.SYS file: 
device=[[drive-][[path JRAMDRIVE.SYS [[disksize ]|sectorsize ]lLentries][{/A\/E\/U } |} 


The following list explains the meaning of each option: 


Option Description 

disksize Disk size in kilobytes. The default size is 64K, the minimum is 
16K, and the maximum is 4096K. 

sectorsize Sector size in bytes. The default size is 512 bytes. The other legal 
values are 128, 256, and 1024. If in doubt, use the default. 

entries Limits the number of root directory entries (files and subdirec- 
tories). The default size is 64, the minimum ts 2, and the maximum 
is 1024. 

/A Uses expanded memory. (This memory must conform to the 
LIM 4.0 specification.) If you use /A, you cannot use /E or /U. 

iE Uses extended memory, making use of addresses above the one- 
megabyte address space. If you use /E, you cannot use /A or /U. 

/U Applicable only to AT&T 6300 PLUS motherboard. Specifies that 


some or all of the 384K of extra memory on an AT&T 6300 PLUS 
motherboard is to be used as an extra RAM drive. 1K of the 384K 
is reserved as overhead for RAMDRIVE.SYS. If you use /U, you 
cannot use /A or /E. 


Any use of RAMDRIVE.SYS or SMARTDRV.SYS uses some conventional memory. 


The versions of RAMDRIVE.SYS and SMARDRV.SYS provided with BASIC are compatible 
with Windows version 3.0, They are not compatible with Windows versions 2.11 and earlier. 


Using SMARTDrive 


The SMARTDRV.SYS device driver lets you use a portion of your computer's memory as a 
disk-cache area. This mechanism serves as a temporary holding area for recently accessed data 
from the hard disk, which significantly reduces data-access time if the desired information is in 
cache. 


You can place the SMARTDrive disk cache in either extended or expanded memory. 
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To install SMARTDRV.SYS, include the following command line in your CONFIG.SYS file: 
device=[[drive:]|[|pathJSMARTDRV.SYS |[normal cachesize ||| munimium cachesize |l{/A |} 
The following list explains the meaning of each option: 


Option Description 


Size of the disk cache in kilobytes. The default size is 256K for 
extended memory and all of available memory for expanded 
memory. Several megabytes is a typical size for a disk cache: 
you'll generally see little difference in performance unless the 
cache is well over 500K in size. 


normalceachesize 


minimumcachesize The smallest disk cache in kilobytes. Windows will reduces disk 
cache to this number when running in real mode.to make more 
memory available for its own use. 


/A Uses expanded memory. If this option is not present, then 
SMARTDrive attempts to use extended memory. 


Generally, the memory assigned to SMARTDRYV.SYS cannot be used by other software. 
However, Code View and Windows can share memory with SMARTDrive. Any remaining 
memory is used for disk-cache operations. 


ISAM Use of Expanded Memory 


By default, ISAM uses about 1.2 megabytes of expanded memory for buffer space (or as much 
as available, whichever is less). This helps to free conventional memory and improves 
performance by providing far more buffers than could exist in conventional memory. 


Depending on how much expanded memory you have, ISAM’s use of 1.2 megabytes may 
affect the performance of other programs that need this memory. To limit the amount of 
expanded memory that ISAM uses, use the /le command-line option with the BASIC Compiler 
or when starting the ISAM memory-resident program: 


/le:emsreserve 
In the syntax above, emsreserve is the number of kilobytes to reserve for other software. The 
setting /le:-1 is a special value that disables ISAM’s use of expanded memory altogether. 


For example, the following command line starts the ISAM memory-resident program and 
reserves 800K of expanded memory for other software, such as QBX or Code View: 


PROISAMD /Ie:800 
Use /le in conjunction with the QBX /Es option if your program code or a loaded Quick library 
manages expanded memory. (See “Competing Use of Expanded Memory” later in this chapter. ) 


Several other options affect how ISAM handles buffers. For complete documentation on how to 
configure and install ISAM, as well as how the number of buffers affects programs, see Chapter 
10, “Database Programming with ISAM.” in the Programmer's Guide. 
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Considerations for QBX 
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The QBX environment and ISAM together require 450K to run (QBX itself requires over 
300K). If you have 640K of conventional memory, QBX will support a moderate-sized 
program without trouble, but large programs may require the use of extended or expanded 
memory, especially if you use ISAM. 


Using the /NOFRILLS Option 


You can use the /NOFRILLS option (abbreviated as /NOF) to make additional memory 
available for program use. However, using /NOFRILLS reduces the functionality of the QBX 
environment. 


When you start QBX and use the /NOF command-line option, QBX uses about 19K less 
memory but does not support any of the following menus: 


e Uutlity menu 
e Options menu 
a Help menu 


The /NOF option does not change the structure of the menu bar or status line, but the three 
menus are unavailable and cannot be opened. 


Extended Memory 


QBX uses extended memory by moving approximately 60K of its own executable code out of 
conventional memory. All the code removed represents space freed for use by your programs. 


When using the HIMEM.SYS device driver, you should set rsrmin to 63 (64.512 bytes) to 
ensure that QBX has access to the high-memory area. The handles field has no effect on QBX, 
since these handles give access to addresses higher than the 64K area which QBX can use. 


For example. the following entry in your CONFIG.SYS file installs HIMEM.SYS and ensures 
that extended memory is available for QBX: 

jJevice=C:\DEVICE\HIMEM.SYS /HMAMIN=63 

When you start the QBX environment, expanded memory may have already been allocated to 


memory-resident programs, most notably ISAM. QBX uses as much of the the remaining 
expanded memory as it needs. 


You can limit the amount of expanded memory used by QBX by using the /E: command-line 
option: 


/E:emslimit 
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In the preceding syntax, ems/imit determines the maximum amount of expanded memory that 
QBX will use, in kilobytes. A value of 0 disables QBX usage of expanded memory and can 


improve the execution speed of some operations. 


Assuming some expanded memory is available, QBX takes advantage of the memory in two 


ways: 


= QBX automatically moves each unit of program code smaller than 16K into expanded 
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memory. Each procedure is a unit of code. The module-level code also constitutes a unit of 


code. 


To see how large each procedure is, use the View SUBs command (press F2). This 
command lists each unit of code together with size in kilobytes, rounded to the nearest 
kilobyte. You can determine which units are larger than 16K and should be divided into 
smaller units (see Figure 7.1). To guarantee best results. View SUBs should show sizes 


ranging from 0 to 15, inclusive. 


a If you give the /Ea command-line option, QBX moves arrays into expanded memory if thes 


do not contain variable-length strings and are smaller than 16K. This option has a 
drawback: arrays residing in expanded memory cannot be passed to modules written in 
other languages (although you can pass array elements). Therefore, you may not want to 


use /Ea with mixed-language programs. 


This option affects all types of arrays except arrays of variable-length strings. which are not 


placed in expanded memory. 


This unit of code is too 
| large to fit in expanded memory. 


Choose program item to edit: 


ClearData 
ClrForm 
ClrHelp 
DataInput 
DataWindow 
Disk Input 
DiskSave 
ErrorMsg 
Help 


CHRTDEMO . BAS 
Axes 
Axis 
AxisScale 
AxisTics 
ChartFonts 
Chart0pt ions 
Chart Type 
ChartWindow 
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| i 
CHRTDEMO.BAS is the main module 


< Edit in Active > « Edit in Split > 


< Delete > 


Figure 7.1 QBX View SUBS Dialog Box 
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Note 


The following QBX command line allows 5OOK of expanded memory to be used and moves 
arrays out of conventional memory: 


QBX /E:500 /Ea 


Once inside the QBX environment, you can determine how much expanded memory is actually 
available to QBX by executing the statement FRE(-3). 


Competing Use of Expanded Memory 


A Quick library can make use of expanded memory directly by using assembly code that calls 
the expanded-memory interrupt. However, Quick libraries that do this must compete with QBX 
for use of the memory. QBX will use as many 16K pages of expanded memory as required, 
according to the rules described in the previous section (assuming that the memory is 
available). 

In order to use expanded memory for Quick libraries, you need to keep two things in mind: 


a You must use the /Es command-line option when starting QBX. This option saves and 
restores the EMS state before and after every ISAM statement or call to a Quick library. 
This save-and-restore operation involves significant overhead. so don’t use it unless you 
have a Quick library that manages expanded memory. 

we Youmay want to limit QBX use of expanded memory by using the /E: command-line 
option. This option is not always necessary, because QBX does not reserve More memory 
than it can use. However. the /E: option is useful for guaranteeing that your program always 
has the expanded memory it needs. 


The following example enables saving and restoring of the EMS state, and restricts the QBX 
environment to using at most SOOK of expanded memory: 


QBX /E:500 /Es 


Considerations for Programmer’s WorkBench 
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PWB uses disk-based virtual memory for loaded source files. This means that the size of the 
program you create is limited only by the amount of free disk space you have and the amount of 
memory available for compiling and linking the program. It is possible, however, to run out of 
memory for PWB itself if you load a large number of PWB extensions or have a memory- 
resident program, such as PROISAM, loaded. 


You can make more memory available in PWB by not automatically loading the extension 
files. The /DA options disables the auto-load function. You can then explicitly load only the 
extensions you need by customizing your TOOLS.INI file. For more information, see the 
section “Loading PWB Extensions Explicitly” in Chapter 4. 
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Considerations for CodeView 


When you debug a program in Code View, three components compete for memory: 

ws The program being debugged 

a The program's symbolic information 

es CodeView itself 

To make the most memory available to the executable being debugged, Code View 
automatically uses expanded memory, extended memory. or disk overlays. In addition, 


Code View provides a utility for compressing program symbol information (CVPACK). For 
more information on CVPACK, see Chapter 5, “Using CodeView.” 


Extended Memory 


If HIMEM.SYS or another extended-memory device driver is installed, CodeView 
automatically places all of the program symbol information and all but 16K of Code View itselt 
in extended memory, leaving the remaining conventional memory available for program 
execution. 


The /X option is not required to use extended memory with Code View, but if you specify /X 
and an extended memory driver is not installed, Code View displays an error. 


Expanded Memory 


If extended memory is not available and RAMDRIVE.SYS. SMARTDRYV.SYS, or a 
compatible expanded memory manager is installed, Code View uses available expanded 
memory for program symbol information and for Code View overlays. 


In order for Code View to use expanded memory, no single modules symbol information can 
exceed 48K. If symbol information exceeds this limit, try reducing filename information by not 
specifying paths when you compile and using /Zd instead of /Zi. 


The /E option is not required to use expanded memory with Code View, but if you specify /E 
and an expanded memory driver is not installed, Code View displays an error. 


Overlays 


If extended or expanded memory are not available, Code View uses 64K disk overlays for its 
executable. You can use the /Dbuffersize option to improve performance by reducing the size of 
the overlay, making more memory available, or increasing the size of the overlay. 

CodeView will not use overlays smaller than 16K nor larger than ]28K. Therefore. the 
minimum effective value for buffersize is 16 and the maximum is 128. 
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